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Structure of the Manual 



This manual is a combination guide and reference to NeWS. 

All of this manual but the Introduction assumes knowledge of the material 
covered in Adobe’s PostScript Language Reference Manual, published by 
Addison-Wesley. If you are unfamiliar with the POSTSCRIPT language, you 
should also consider the companion book PostScript Language Tutorial and 
Cookbook required reading. 

Tht NeWS Technical Overview is a useful introduction to the concepts and 
benefits of NeWS. 

General help may be found in Appendix A, Using NeWS, and you can work 
through the examples in the PostScript Language Tutorial and Cookbook using 
News’s psview command. 

The manual is organized as follows: 

□ An introduction to the design and goals of NeWS. 

□ An overview of the NeWS extensions, 

□ Further information about the extensions for handling input and events. 

□ An overview of the POSTSCRIPT language files that implement additional 
server functionality and packages. 

□ Descriptions of some of the packages implemented in these POSTSCRIPT 
language files: 

• an extended input system 

• a complete classing mechanism 

• example window and menu packages based on this class mechanism 

• a debugging facility 

□ A description of the CPS program, used to construct C client interfaces to 
News. 

□ A complete example client program. 
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Preface — Continued 



□ Reference chapters for the NeWS types and operators. 

□ A section detailing the areas in which the current POSTSCRIPT language 
implementation is incomplete. 

□ A reference section for the format of the byte stream communication 
between the clients and the server, detailing the data compression techn 
available. 

□ Information on font support in NeWS. 

□ An appendix on how to start up NeWS, with some advice on programmii 
News and customizing the NeWS server. 

□ An appendix with a complete listing of all the NeWS operators, sorted al 
betically and by class. 

□ Details of another class package, Liteltem, used in the it emdemo den- 
program. 

□ An appendix containing manual pages for NeWS. 

Font Usage The NeWS Manual includes code and procedures from two different languag 

and the POSTSCRIPT language. We have used fonts to clarify which langua 

used. This differs from other Sun manuals: 

bold listing font 

This font indicates things that you should type at ya^'t v 
tation. 

listing font This font indicates literal values such as file names and 
put displayed by the computer. It also indicates use of i 
language: it is used in C program listings and C procedi 
names. CPS routines and code fragments such as 
ps_open_PostScript ( ) are printed in this font. 

sans serif font This font is used for PostScript program listings, type 
code fragments such as 300 200 createcanvas map( 
vas to distinguish them from C code. It is also used in 
definition of NeWS functions (primarily in Chapter 12, A 
Operator Extensions), 

bold font Unfortunately, sans serif fonts look poor in the middk 

normal text. So, as well as indicating cautions and war 
bold font is used to indicate all NeWS names, such as 
clipcanvas, when they appear in paragraphs or the inde 

italic font This font is used as a place holder for words, numbers, 

expressions that you define, for example parameters to 
mands, and operands of POSTSCRIPT language operatoi 
Italics are also used in the conventional manner to emp 
important words and phrases. 
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Introduction 



News is a distributed, extensible window system that takes a long-term approach 
to the development of user interface and display technology. It is not an attempt 
to codify and build on existing systems; it is rather an attempt to step up to a new 
level of technology. The unique feature of NeWS is the ubiquitous use of an 
extension mechanism. The extensibility of the system is the key to integrating 
windows efficiently into a distributed environment. Performance is enhanced by 
close interaction between clients and their server, communication is speeded up 
by application-specific data compression, semantic issues are reduced by a cen- 
tral authority, and user interface issues are easier to address. 

News is based on a novel sort of interprocess communication. Interprocess com- 
munication is usually accomplished by sending messages from one process to 
another via some communication medium. Messages are usually streams of 
commands and parameters. One can view these streams of commands as pro- 
grams in a very simple language. What happens if this language is extended to 
become Turing-equivalent? Programs no longer communicate by sending mes- 
sages, they communicate by sending programs that are elaborated by the 
receiver. This has interesting effects on data compression, performance, and 
flexibility. 

The PostScript programming language defined by John Wamock and Charles 
Geschke at Adobe Systems is used in just this way."^ What Wamock and 
Geschke were trying to do was communicate with a printer. They transmit pro- 
grams in the POSTSCRIPT language to the printer, which are elaborated by a pro- 
cessor in the printer, and this elaboration causes an image to appear on the page. 
The ability to define a function allows the extension and alteration of the capabil- 
ities of the printer. 

This idea has powerful implications within the context of window systems: it 
provides a graceful way to make the system much more flexible and it provides 
some interesting solutions to performance and synchronization problems. For 
example, if you want to draw a grid, you don’t have to transmit a large set of 
lines to the window system, you just send a program containing the appropriate 
iteration. Downloading programs in an extension language is not just a nice 
feature that has been tacked on; it is an integral part of the window system. 

News extensions conform to the form of POSTSCRIPT primitives. The 
PostScript language is clean and simple, it has a well-designed graphics model, 
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and it is compatible with many of the printers available today. 

News is a single process, which acts as a network server and contains a 
PostScript language interpreter ^ Within this server process is a collectior 
lightweight processes that execute POSTSCRIPT programs. A lightweight pn 
is unlike a typical UNIX process in that it shares a data space with other ligh 
weight processes. Consequently, process creation has very little overhead aj 
characterized by great rapidity. 

Client programs talk to NeWS through byte streams. Each of these streams g 
erally has a lightweight process within the NeWS server that executes the stre 




Figure 1-1 Client — Server Interaction in 

Messages pass between client processes, which exist somewhere out on the 
work, and NeWS processes, which exist within the NeWS server. These proce 
can perform operations on the display and receive events from the keyboarc 
the mouse. They can talk to other NeWS processes, which may, for example 
implement menu packages. 

News centers around the POSTSCRIPT language. All that is provided by NeWi 
set of mechanisms; policies are implemented as POSTSCRIPT procedures. F 
example, NeWS has no window placement policy. It has mechanisms for ere 
windows and placing them on the screen, given coordinates for the window 
choice of those coordinates is up to some POSTSCRIPT procedure. 

What is usually thought of as the user interface of a window system is expl 
outside the design of this window system. User interface includes such thir 
how menu title bars are drawn and whether or not the user can stretch a win 
by clicking the left button in the upper right hand comer of the window out) 
All these issues are addressed by implementing appropriate procedures in tl 

^ News was conceived and created wholly by Sun Microsystems. 
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PostScript language. 

The rest of this section presents NeWS in four parts: the imaging model, window 
management, user interaction, and the client interface. The imaging mode! refers 
to the capabilities of the graphics system — the manipulation of the contents of a 
window. Window management refers to the manipulation of windows as objects 
themselves. User interaction refers to the way a user at a workstation interacts 
with the window system (e.g., how keystrokes and mouse actions are handled). 

The client interface defines the way in which client programs interact with the 
window system (e.g., how programs make requests to the window system). 

1.2. Imaging Imaging in News is based on the stencil/paint model, essentially as it appears in 

Cedar/Graphics^ and the POSTSCRIPT language. A stencil is an outline specified 
by an infinitely thin boundary composed of spline curves in a non-integer coordi- 
nate space. Paint is some pure color or texture — even another image — that 
may be applied to the drawing surface. Paint is always passed through a stencil 
before being applied to the drawing surface, just like silkscreening. This is the 
total model. Lines and characters can be defined using stencils. Lines are done 
as long, narrow stencils. 

One of the attractive characteristics of this imaging model is its very abstract 
nature. For example, the definition of a font allows many implementations: as 
bitmaps, as pen strokes, or as spline oudines. No commitment is made about 
exactly which pixels are affected, or even that there are pixels at all. The exten- 
sion of the system to deal with anti-aliasing does not affect the interface. The use 
of a very abstract imaging model provides a very high degree of device indepen- 
dence. 

The specification of this model is simple and elegant, but the way in which its 
various features can be combined leads to a tricky implementation. For example, 
the mechanism for specifying a stencil allows straight lines, arcs, and higher- 
order curves to be a part of its boundary. Stencils can be used both for clipping 
and for filling. This implies that it must be possible to compute the intersection 
of curved boundaries. 

News implements curves with conic splines.^ Curves form paths, or shapes, and 
News has a set of algorithms for manipulating these paths.^ These algorithms 
have been assembled into a library that supports the stencil/paint model. The 
News server is implemented as a language interpreter that knows nothing about 
imaging, but calls routines in this library to perform all imaging operations. 

1.3. Canvases News’s basic drawing surface is a canvas. This non-standard term was picked to 

avoid the semantic confusion that surrounds the word ‘window.’ A canvas is just 
a surface on which an image may be drawn. The surface may be either opaque or 
transparent, and can have any shape. Canvases are laid out in two-and-a-half 
dimensions on a display surface; in other words, they can overlap. The actual 
implementation of canvases depends heavily on the graphics package described 
in the previous section. A canvas may keep a portion of its image off-screen in 
order to facilitate quick refresh of its image when uncovered. In addition, a can- 
vas may be drawn to while not displayed and then mapped to the display that 
renders it visible; this is a method for double-buffering. 
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Canvases are cheap and easy to create. Menus, windows, and pop-up rr/ 
are all based on canvases. NWS has extensions in the form of primitive? lu ^ 
and manipulate canvases. All POSTSCRIPT graphics operations are perform( 
some canvas. 



1.4. User Interaction 
Input 



Events are distinguished by where they occur, what happened, and to what, 
objects spoken about here are usually physical; they are the things that a pei 
can manipulate. An example of an event is the [H] key going down while t 
mouse is over canvas x. This might trigger the transmission of the ASCII c 
for E to the process that created the canvas. The bindings between events a 
actions are very loose and easy to change. 

The actions to be executed when an event occurs can be specified in a genei 
way, via the POSTSCRIPT language. The striking of the (E key sends a me 
to a News process that is responsible for deciding what to do with it. The pi 
can do something as simple as sending the message to a UNIX process, or a 
complicated as inserting the message into a locally maintained document. 

PostScript language procedures control much more than just the interpret 
of keystrokes. They can be involved in cursor tracking, constructing borde 
around windows, doing window layout, and implementing menus. Ths^^p 
cedures strongly resemble the Bell Labs squeak language, with lightw^^t 
processes replacing concurrency compilation.^ 



Each possible input action is an event. Events are a general notion that incli 
buttons going down and up (buttons may be on keyboards, mice, tablets, or 
ever else) and locator motion. They are implemented as messages between 
processes. 



1.5. Client Interface 



A client program exists in two parts: one part is written in the POSTSCRIPT 
language and lives inside NeWS, and one part lives outside NeWS and talks t( 
through a byte stream. This leads to a number of levels at which the client 
face can be viewed. 

□ At the lowest level, the programmer writes POSTSCRIPT language prog 
and deals with an entirely POSTSCRIPT language universe. Menu pack 
and window layout policies are examples of objects that will usually b 
implemented this way. 

At this level. News provides conventions that define an object-oriented 
face to windows, menus, selections, and so on. Objects inherit a defai 
of behaviors, but these can be overridden selectively. 

□ One step above that, the programmer writes programs in C, or some oi 
language, that generate POSTSCRIPT language programs. The progran 
explicitly aware of the existence of the POSTSCRIPT language. News e 
tors of other window systems are generally implemented this way. 

At this level, NeWS provides a C pre-processor that allows C programi 
cross the language boundary to the POSTSCRIPT language easily. In el 
they can write C procedures with POSTSCRIPT language bodies. Anah 
tools for other languages are possible. 
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□ At the highest level, the existence of the POSTSCRIPT language and message 
passing is completely hidden by an interface veneer that someone else has 
constructed using the second-level facilities. News appears as a set of rou- 
tines that are called in the normal way. 

As with the user interface, News defines no details of the programmer’s interface 
and permits it to be specified by POSTSCRIPT programs. The programmer’s inter- 
face may even be created on a per-application basis, by writing POSTSCRIPT pro- 
grams. 

1.6. Background and Goals In some respects. News represents a major break with the technology used in 

current window systems. In other respects, it is very similar to some existing 
systems. This section examines these differences and similarities, relating them 
to the overall design goals of NeWS. 

Device Independence Most current window systems, including SunWindowsJ^ MIT’s Xp and 

Camegie-Mellon’s Andrew P are based on the RasterOp and pixel coordinate 
imaging model. As graphics hardware evolves to provide better performance, 
this model becomes less appropriate: 

□ The model preempts the use of advanced transformation and rendering 
hardware by insisting clients break down their graphical operations to such a 
low level that the hardware is useless. Current window systems mean that 
powerful hardware assists only those clients which take special measures to 
use it. 

□ The model ensures that clients are aware of the actual size of individual pix- 
els on the display, since the only coordinate system they have is that pro- 
vided by the hardware. Until recently, this has not been a severe problem 
because the pixels on displays in use have all been within 30% or so of 80 
dots to the inch. But displays up to 300 dots to the inch are already becom- 
ing available, and resolutions may go much higher. 

□ The model doesn’t extend in a clean and useful way to color. Boolean com- 
bination functions between color pixel values don’t make much sense. For 
instance, one often draws transient rubber band lines by XORing them with 
the image. XORing color map indices can lead to some pyrotechnic effects. 
Furthermore, the model exposes the differences among the three common 
ways that color is represented in display devices: 1-bit black and white (con- 
stant small set of colors), 8-bit color with a colormap (variable small set of 
colors), and 24-bit color (all possible colors available everywhere). Clients 
have to invoke different operations for each display type. 

News’ more abstract imaging model allows advanced transformation and render- 
ing hardware to assist all clients; clients do not have to determine if it is available 
and take special measures to use it. News clients need not be concerned with the 
hardware coordinate system; they define their own. 

News clients also need not be concerned with any dependencies on a particular 
color model or on color hardware. NeWS allows clients to specify colors as 
red-green-blue values or as hue-saturation-brightness and will make its best 

#sun 
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efforts to display the correct colors on the screen. On full-color displays^ ^ 
displays the exact color. On color-mapped displays, NeWS selects the clo^s^ 
color table entry to the requested color. On monochrome and gray-scale 
displays, NeWS will use dithering and half-toning techniques as necessary. Ir 
way, clients expend minimal effort to get usable output on a wide variety of 
displays. 

A similar problem of device-dependence exists on the input side of current v 
dow systems. They implement a fixed set of devices, and the client has to bt 
aware of the set. In many cases, the client has to determine which devices at 
ally are present and load appropriate keyboard mapping tables. In News, arl 
trary transformations of input events may be programmed in the POSTSCRIF 
language, so each client can be presented with an appropriate set of input de 
ices, and new and unanticipated devices can be accommodated. 

Portability Even if current window systems did not expose so much of the underlying 

display hardware, many would not be portable between different machines, 
terns that are implemented largely as part of the operating system kernel, sue 
SunWindows, demonstrate this problem. 

NeWS, like X and Andrew, is a user-level server process. Both these predece 
have been ported with relatively little effort to a range of workstations. NeW 
like Andrew in that it has been designed from the start to be ported. A wind 
system that is available over a wide range of workstations and displays is be 
ing a necessity for the UNIX marketplace. 

Flexibility Some current window systems, Andrew and the Macintosh^ are examples, S( 

to impose a single consistent user interface style on their clients. This has g 
productivity benefits, both for the user and the programmer. Users can lean 
applications easily, because they behave the same as the last application lea 
Programmers can inherit much of the user interface of a new application fre 
“canned” application like MacApp. 

Other current window systems, X and Smalltalk^ are examples, observe that 
wide range of interface styles are already in use and that a specialized interf 
can make an experienced user more effective than any single consistent inte 
They set an explicit design goal of avoiding specifying a user interface styh 
other window systems the style is determined for the most part by libraries 
into each application, and is very difficult either to change or to make consi 

News attempts to address both aspects of this dilemma. The server does no' 
depend on any details of the user interface; it is written in the POSTSCRIPT 
language and thus are easily changed. The way the lightweight News proce 
share their name spaces encourages clients to share user interface compone 
such as menus, scrollbars, and so on. These shared components are typical] 
inherited from the global POSTSCRIPT language environment, and are thus < 
sistent across the range of clients. They can be replaced for all applications 
changing the global environment. The effect is that unless clients explicit!; 
override the default behavior, they are consistent in their user interface. 
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Distribution Both Andrew and X have demonstrated that windows can be presented as a net- 

work service, available to clients anywhere, and can provide adequate perfor- 
mance for most tasks. In a highly networked environment, a window system that 
restricts clients to running on the machine with the display is unnatural. 

Like these systems, News is a network window server whose clients can be any- 
where. However, it takes the provision of adequate performance a step further. 
The ability to write the parts of a user interface needing instantaneous response, 
such as rubber-band lines, in the POSTSCRIPT language and have them executed 
by the server without client intervention solves one of the critical performance 
problems of current systems. The ability to down-load interpreters for special, 
application-specific protocols allows better use to be made of the limited network 
bandwidth. 

Graphics A window system that provides only RasterOp, lines, and simple text makes the 

construction of graphically interesting interfaces difficult. The Macintosh, for 
example, is a system that has a richer graphics model and as a result has a flair 
for more interesting interfaces at the cost of a somewhat more complex applica- 
tion programmer interface. News’s use of the higher-level stencil/paint imaging 
model provides advanced imaging capabilities without increasing the apparent 
complexity. 
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News Extension Overview 



News implements a number of extensions to the POSTSCRIPT language (as 
specified by Adobe in the PostScript Language Reference Manual) which are 
specific to News for the purposes of interactive behavior. These extensions 
include new types and new operators. The POSTSCRIPT language was initially 
designed for driving printers. As a part of NeWS, the POSTSCRIPT language inter- 
preter has to deal with multiple asynchronous clients, interaction, displays, key- 
boards, and locators. This chapter is an overview of the NeWS extensions in the 
areas of lightweight processes, canvases, colors and cursors. For a full descrip- 
tion, see Chapter \ \,N^S Type Extensions and Chapter \2,N^S Operator 
Extensions. 

Many application programmers will not be concerned with most of the primitives 
described here. They will use instead the packages that have been defined using 
these primitives to support windows, menus, and the like. These packages of 
PostScript language code are described starting in Chapter 4, Extensibility 
through PostScript Language Files. 

2.1. The Lightweight The News server maintains a set of simultaneously executing lightweight 

Process Mechanism processes. Each process is an individual thread of control with its own graphics 

context, dictionary stack, execution stack, and operand stack. These processes all 
exist in the same address space; two processes can refer to the same object if they 
can both locate the object. Typically, each connection to the server obtains a 
separate thread of execution, with its own context. This thread can fork new 
threads and form a group of NeWS processes. Such groups of processes are 
represented by process objects. 

Processes can fork new processes, kill them, wait for them to die and obtain a 
return value, pause to allow other processes to run, suspend themselves and 
other processes, continue suspended processes, and examine the state of other 
processes by opening the process objects that represent them as dictionaries. 

The lightweight process scheduling policy is non-preemptive (a process contin- 
ues to execute until it blocks) and serial (only one process is active at a time). 
Processes block by executing file I/O requests, the pause or suspendprocess 
primitives, or awaitevent. 

NOTE The current scheduling policy might change to pre-emptive scheduling in the 
future. Thus, it is unwise to write POSTSCRIPT language code that relies on the 
behavior of a non-pre-emptive scheduling policy. POSTSCRIPT language code 
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2.2, Canvases and Shapes 



Visibility 



Damage 



that accesses shared data structures should use monitors to protect thc^-^^d 
structures, 

A canvas is a surface upon which are drawn using the POSTSCRIPT languag 
Each News process has a canvas associated with it called the current canva 
Canvases exist in a hierarchy. At the root of a hierarchy is a device canvas 
device canvas is created as the result of the createdevice operator and repr 
the background, sometimes called the “desktop.” Additional canvas obje( 
may be created with newcanvas calls. 

A canvas can be repositioned in the list of its siblings with canvastotop an 
vastobottom. Its x,y offset relative to its parent may be set with movecan' 
canvas may be inserted inserted above (insertcanvasabove) or below (ins( 
vasbelow) another canvas. 

Canvases need not be rectangular. Their shape may be set with reshapeca 
to be the region outlined by the current path. Each canvas also has associa 
with it a default transformation matrix. The reshapecanvas operator sets ; 
vas’ default transformation matrix from the current matrix. 

If a canvas is to be visible on a display device, it and its ancestors must be 
mapped. Canvas mapping is controlled by the Mapped field of a canvas, 
is a boolean value. When a canvas is created, it is initially unmapped, so t 
value of its Mapped field will be false. Setting this field to true and false 
map and unmap the canvas from the display. 

A canvas may be transparent: its image does not obscure any image drawi 
underneath it by a parent or sibling. Any image drawn on a transparent ca 
drawn on its parent. A non-transparent canvas is referred to as being opaq 
Transparency is controlled by the Transparent field of a canvas, a boolea 
Transparent canvases are useful for defining areas that are sensitive to inpi 
that do not interfere with drawing in other canvases. 

A canvas is considered to have damage if all or part of its image does not 
There are several ways that damage can occur. A canvas may become dai 
when, for example, another canvas is moved away from it, exposing the fi 
vas. The entire canvas is considered to be damaged when it is first mappe 
the screen (if it is not retained) or when it makes the transition from non-r 
to retained. The entire canvas is also considered to be damaged whenever 
reshaped. 

All programs have to cope with canvas damage and must be able to recon 
the damaged part. An opaque canvas may be retained; that is, any portioi 
canvas obscured by other canvases is saved in some offscreen area. Wher 
these obscured areas is exposed, the offscreen copy is simply moved onto 
screen. If the canvas were not retained, there would be no copy, and the c 
would be damaged. Retaining a canvas is purely a performance enhancer 

Damage can be spread with copyarea, which copies a region on the canvj 
one place to another. If part of the source is damaged, the corresponds^ 
tion area becomes damaged. 
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Event Consumption 



Offscreen 



Damage accumulates on a canvas until some process responds to it. Each opaque 
canvas has a record of its damaged regions. As more damage occurs, this record 
is enlarged. The damagepath operator sets the current path to an outline that 
encloses all the damaged parts of the canvas, and clears the damage record. The 
sequence of events followed to deal with damage repair is generally: 

□ Damage occurs on an opaque canvas. 

□ A /Damaged event is generated. 

□ A News process receives the event. 

□ The News process sends a message to the client program informing it that 
damage has occurred. 

□ The client program receives the message and sends a message back to ini- 
tiate the repair. 

□ When the repair initiation message is received by a NeWS process, it executes 
damagepath cHpcanvas for the opaque canvas that was damaged. 

□ The News process may send back a description of the region damaged. 

□ The client program sends a News program to the server that will redraw the 
damaged region (or it will draw the whole window and let the clipcanvas 
operation throw away irrelevant operations). 

□ The client program sends an end-of-repair message that executes newpath 
clipcanvas. 

This multi-level handshake is used so that the client and server can proceed asyn- 
chronously and yet be properly synchronized when they deal with damage. 

Canvases also have a property that controls their behavior with respect to input 
events. The EventsConsumed field controls what happens to events that occur 
on this canvas. The EventsConsumed field can have one of three keyword 
values: /AlIEvents, /MatchedE vents, or /NoEvents. If EventsConsumed 
equals /AlIEvents, all events on this canvas are consumed by it. That is, no can- 
vas behind this one will receive any events. If EventsConsumed equals 
/MatchedEvents, then events that match an interest on this canvas will be con- 
sumed, while non-matching events will be passed through to canvases behind 
this one^. Finally, if EventsConsumed is equal to /NoEvents, no events will be 
consumed, and all will be pass through to the canvases behind. 

A News program can maintain an offscreen image by use of a canvas that is 
retained, unmapped, and opaque. A process can draw in one of these canvases in 
the same way it draws on other canvases, the only exception being that the image 
will not appear on the screen. One way to have the image appear is to simply 
map the canvas onto the screen. Another way of having the image appear is to 
use the imagecanvas operator to copy the image from the offscreen canvas to an 
onscreen canvas. 



^ For an explanation of interests and events, see Section 3.3, Interests: Event Selection of Chapter 3, Input. 
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Cursor Every canvas has a cursor image that is displayed whenever the mouse ^ \ 

over the canvas. This image is set with setcanvascursor and retrieved wifti 
getcanvascursor. A child canvas inherits its parent’s cursor upon creation ( 
canvas. A cursor image is composed of a black primary image and a white 
image. These images are superimposed on their origins. These images are ^ 
ing more than characters in a font. The hot spot of a cursor (the pixel coord 
to which the mouse is pointing) is the origin of the primary image’s characu 

The current location of the cursor in the current coordinate system is retume 
currentcursorlocation. Similarly setcursoriocation will move the cursor i 
new location. We discourage use of setcursoriocation because it causes di: 
certing cursor jumps. 

2.3. Colors The PostScript language has a notion of color, which is implemented in tf 

sethsbcolor and setrgbcolor primitives. NeWS extends this notion by addin 
color type. Objects of type color can be created with either the HSB or the 
color model. Color objects can also be compared with the contrastswithcu 
primitive. 
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Input 



Printers don’t receive input from the user; conversely, window programs do 
much more than display graphics. For example, they usually change their 
display in response to outside events such as mouse clicks. Hence, input han- 
dling in News is a major extension to the POSTSCRIPT language. This chapter 
describes the primitive data structures and operations for handling input in News. 
These primitives provide a minimal user-input system. More sophisticated user- 
interfaces can be constructed entirely in the POSTSCRIPT language on top of these 
primitives (for example, the Extended Input System described in Chapter 5, The 
Extended Input System ). 

3.1. Input Events Input in NeWS is treated as a series of events that are received, translated, 

dispatched, and routed by the server to its clients. Events are structured objects. 
They contain a number of fields, which are accessed as though the event were a 
dictionary and the fields were keys in that dictionary. Most of these fields are 
mentioned as they become relevant in this chapter. The full definition of event 
fields can be found in Chapter 1 1 , iVeWS Type Extensions. The POSTSCRIPT 
language interface is structured in such a way that adding fields does not affect 
existing POSTSCRIPT programs. 

Among the most interesting fields in an event are: 

o An event Name (a POSTSCRIPT language object — generally a small number 
to represent a character, or a keyword such as /LeftShift or 
/MouseDragged, but any object is legal. 

a An event Action (another POSTSCRIPT language object, with more variety in 
common types and semantics). 

□ A TimeStamp, which shows when the event happened. 

□ A Canvas and a coordinate pair (XLocation, YLocation), which give an 
event location in terms of the cursor position at the time of the event. 

Many events are generated by the system to report user actions like mouse 
motion and key presses. Events can also be generated by News processes, and 
submitted for processing just like system-generated events. The createevent 
primitive leaves a new event on the stack with null or 0 in all fields. The copy 
primitive can be used to copy the fields of one event into another en masse. This 
extension of the copy primitive is closely analogous to its usage with two dic- 
tionaries. (For the integrity of the input system, the event’s Isi merest flag, 
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Serial number and IsQueued fields are not copied.) 

3.2. Submitting Events for Any event can be passed into the distribution mechanism to be received by a 
Distribution process whose interests it matches. Three primitives are used in this context 

sendevent 

takes an event off the stack. The event is sorted into the event queue an 
distributed as described below in Section 3.4, Event Distribution. 

recallevent 

takes an event off the stack and removes that event from the event queui 
This implies that the event must have been put in the queue by sendeve 
since no process will have a reference yet for system-generated events, 
also requires that the client must have saved some reference to the even 
given to sendevent, in order to pass the same event to recallevent. 
recallevent is useful for turning off a timer event that has been sent but 
yet delivered. 

redistributeevent 

takes an event (which should have been received by this process via 
awaitevent, or be a copy of such an event) and resumes the distributior 
cess right after the interest that resulted in the event’s delivery to this p 
cess. (The following sections provide detailed discussions of interests.^ 
This behavior is useful when a process receives an event via an exclush 
interest (described below) and now needs to continue distribution (perh 
after modifications) as though the interest had not been exclusive. 

redistributeevent does not return events to the event queue; recall^ei 
will not work on a redistributed event. An interest that has been tested 
for a match against an event will not be tested again when the event is i 
tributed; an interest will never match the same event twice. It is pointlt 
pass an event that has never been distributed to redistributeevent; the 
will simply be discarded. 

Processes indicate their interest in receiving events by constructing one or r 
ideal events resembling what they want to receive and passing each ideal e^ 
as an argument to expressinterest. In other words, to get a particular kind i 
event, create an event like it and express interest in that event. An event thi 
been used as an argument to expressinterest in this way is called an interei 
When real events are generated and distributed, they are are matched to inte 
on the Name, Action, Canvas, and Process fields. Non-specific (“wild-ca 
matches may be specified, as described under Section 3.4.2, Event Matching 
below. Two other event fields that affect the matching behavior of an inten 
its Exclusivity and its Priority; their effects are described under Section 3. 
Order of Interest Matching below. 

An expression of interest may be canceled by revokeinterest. When intere 
expressed in an event, its Isinterest field is set to true. Isinterest is false f< 
events if: 

□ they have never been passed to expressinterest. 
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D they have subsequently been passed to revokeinterest, 

□ the process that expressed the interest has terminated, or 

□ the canvas on which the interest was expressed is destroyed. 



Changing and Reusing 
Interests 



Inquiring for Current 
Interests 



3.4. Event Distribution 



Receiving Events 



Event Matching 



The Name and Action of an interest may be changed while it is active, and the 
change will be reflected in the next match attempted against that interest. How- 
ever, changes to other fields in the interest will not be recognized and should not 
be attempted. Rather, the interest should be revoked, the modifications per- 
formed, and then the interest should be expressed again. 

If an interest is used as the argument to a second invocation of expressinterest 
before it has been revoked or otherwise inactivated, the second expression of 
interest overrides the first. If the same process expresses interest in the same 
event twice in succession, the second expression is ignored. 

The set of interests which are currently active for any canvas or process may be 
retrieved as an array of events, by treating the canvas or process as a dictionary, 
and getting the value associated with the Interests key. This mechanism is 
described fully in Chapter 1 1, iVetV5 Type Extensions. Similarly, the global 
interest list (the set of interests which have been expressed with null in their 
Canvas) is returned by the operator globalinterestlist. The result is an array of 
events, ordered on priority (highest first). 

Input events enter the system as they are generated by the News server, or when a 
process executes sendevent or redistributeevent. Events generated by the 
server are stamped with the time of their creation; other events have whatever 
TimeStamp is left by the process that provides them. (A process can use the 
currenttime and lasteventtime primitives to generate a value for the 
TimeStamp field.) In any case, newly received events are sorted into a single 
event queue according to their TimeStamp values. 

Events are removed from the head of the event queue one at a time as the server 
schedules processes to be run. No event will be distributed before the time indi- 
cated in its TimeStamp. Copies of the event are distributed to all processes 
whose interests it matches and each of those processes is given a chance to run 
before the next event is taken from the queue. 

A process gets its next input event by executing awaltevent. If no event has 
been distributed to it, the process will block. If a distributed event is waiting, 
awaitevent will return immediately, with the new event on the top of the operand 
stack. 

Matching between a real event and an interest is defined as follows: 
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Name and Action Matching 



Canvas Matching 



Process Matching 



Processing after an Interest 
Match 



□ The Name and Action fields are treated the same. 

□ Null in an interest field matches anything in the corresponding field of 
real event. 

□ A simple object (boolean, keyword, or number) in the interest matches 
same value. 

□ An array or a dictionary in the interest specifies a class of values the re 
event may match. A real event value matches if it is any of the elemer 
the array, or keys in the dictionary. 

A null Canvas in the interest matches events not directed to a specific canv 
This includes keystrokes and mouse-button/motion events. A non-null can 
the interest will match events occurring when the cursor is within that canv 
other events with the canvas field set to that canvas (e.g., /Damaged events 

The Process field of an interest is set by expressinterest (to the process exi 
ing the interest). Normally, events being distributed have null in their Pro( 
fields and will be matched against interests without restriction. If an event 
specific process in its Process field, the event will only match interests that 
been expressed by that process. (It must still match the interest on Name, 
Action, and Canvas.) 

If all of these conditions are met, the event matches the interest. 



When an event matches an interest, a copy of the event is generated, 
copy, the Interest and Canvas fields are set to the interest and canvas mtitc 
If the Name and/or Action values matched a key in a dictionary in the 
corresponding field in the interest, one of two things will happen: 



1 . If the value in the dictionary corresponding to the matching key is not 
cutable, then that value is stored in the Name or Action field in the ev 

2. If the dictionary value is executable, then the value in the correspondi 
field of the event is not modified; instead, the executable object from t 
tionary is queued for execution in the receiving process immediately < 
the event is returned by awaitevent. 

If both the Name and Action fields of the event have such executable 
matches, the Name is executed first, then the Action. 



Then the copy of the event is placed on a private queue for the process tha 
expressed the interest; if that process was blocked in awaitevent, it is mad 
runnable. The original event then may be matched against further interest 



^ The null-canvas option of an interest is not logically necessary; the same effect can be achieved I 
interest expressed on an overlay canvas for the root window. This overlay style has an additional bent 
allows recursive window managers. The null option has been retained for coding convenience among 
willing to forego the generality. 
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Order of Interest Matching 



Interest Lists 



Multiple Matches 



An event that is being distributed may potentially match more than one interest. 
This section describes which interests will be satisfied by the event. The order in 
which interests are considered for a match during the distribution of a real event 
is determined by the interest list each belongs to and by their order within those 
lists. 

Each interest is contained in one interest list. There is an interest list for each 
canvas; it holds all the interests that have been expressed on that canvas. There 
is also one global interest list, which contains all the interests expressed with a 
null Canvas field. An interest will never appear in more than one interest list, 
and any interest list may be empty. 

When an event is being distributed, its Canvas field is checked, and if it is non- 
null, the event is matched only against interests on that canvas’ interest list. If 
the real event’s Canvas is null, the real event is first matched against interests on 
the global list. If none matches, it is matched against interests on the lists of can- 
vases that contain the event’s location. Canvas-specific interest lists are taken in 
leaf-to-root order in the canvas tree. That is, the interest-list of the front-most 
canvas is considered first, then the interest-list of its parent, then its parent, etc. 

Within each interest list, the interests are ordered on their Priority field; higher 
numeric values come first. Among interests on the same list with the same 
Priority, the last-expressed interest is tested first. 

The sequence of testing against interests continues until it is stopped by one of 
the following conditions: 

1. Any interest may have its Exclusivity field set true; if so, an event that 
matches that interest will not be considered against any further interests. 

2. A canvas may absorb events, so that they are not tested against interests on 
any canvas behind it. This is controlled by the canvas’ Event sConsumed 
field. 

□ If EventsConsumed is set to /AllEvents, no event that hits the canvas 
will be considered against the interest list of any canvas that lies behind 
it. 

□ If EventsConsumed is /MatchedE vents, events that match an interest 
on that canvas’ list will be stopped, but others will pass through. 

□ If EventsConsumed is /NoEvents, events will be considered against 
interests on canvases farther back, regardless of whether they matched 
an interest on this canvas. 

In these terms, the global interest list acts as if it were a list on a canvas that con- 
sumes MatchedE vents; events that match an interest on the global list don’t get 
through to any canvas-specific list, unless they are explicitly redistributed. 
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3.5. Special Event Types 



Actions for Enter and Exit 
Events 



News generates a number of different input events. Keystrokes general!^ ^ 

numeric values in their Name, but most others are identified by a keywwo^ 

Name. The most important event types are described here. 

□ /Damaged: Damage events are generated for a canvas whenever it is di 
aged. By the time a process repairs the damage, several events may ha- 
accumulated. The total damage is accessible with damagepath. The 
Action for a damage event is null, and the Canvas field identifies the 
affected canvas. 

a /EnterEvent, /ExitEvent: When the cursor is moved across a border 
between canvases, multiple events are generated. In each event, the Nt 
either /EnterEvent or /ExitEvent, depending on the direction of the cr 
ing. Details of the Action are described in the next section. 

□ /MouseDragged, /LeftMouseButton, /MiddleMouseButton, 
/RightMouseButton; Manipulation of the mouse generates events with 
these names. If the mouse moves, the event Name is /MouseDragged 
the Action is null. If a mouse button is pressed or released, the Name 
identifies which button is affected and the Action is one of the key wore 
/DownTransition or /UpTransition. 

□ Timer events: There are no special timer events in NeWS; rather, the gu; 
tee that no event will be delivered from the event queue before the timt 
TimeStamp means that any event can be used to generate another ever 
some time in the future. The example program at the end of this ch^t< 
illustrates a timer event. 

There is no requirement that a process send a timer event to itself; it ca 
as easily send a delayed message to another process, or broadcast one, 
changing the Process field in the event passed to sendevent. 



Window-crossing events are generated whenever the cursor crosses the bou 
between two canvases. Each such event is directed to a particular canvas 
(identified in the Canvas field of the event) and each specifies how the cun 
moved with respect to that canvas. 



The Name field of the event is either /EnterEvent or /ExitEvent. The Aci 
field of the event is 0, 1, or 2. The definitions below ease the explanation c 
these values mean. 

Let us say that the frontmost canvas under the cursor directly contains the ' 
Then a canvas is directly affected by a crossing if it directly contains the ci 
either before or after the crossing. (If the same window directly contains tl 
sor both before and after an event, there is no crossing.) 

A canvas may also be indirectly affected. This happens when the canvas ii 
directly affected, but the cursor crosses into or out of the canvas’ subtree, 
is, a canvas is indirectly affected if it is an ancestor of either the canvas ths 
directly contains the cursor before the crossing or the canvas that directly ( 
tains the cursor after the crossing, but not both. (If a canvas is ancestoj^a 
canvases that directly contain the cursor both before and after a crossi^^i 
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affected.) 

The following table explains the six combinations of Name and Action for cross- 
ing events. 

Table 3-1 Boundary Crossing Events 



Name 


Action 


Explanation 


/EnterEvent 


0 


The canvas now directly contains the cursor; the 
previous direct container was not a descendant 
of this canvas. 




1 


The canvas now directly contains the cursor; the 
previous direct container was a descendant of 
this canvas. 




2 


The canvas now indirectly contains the cursor; 
the previous direct container was not a descen- 
dant of this canvas. 


/ExitEvent 


0 


The canvas used to directly contain the cursor; 
the new direct container is not a descendant of 
this canvas. 




1 


The canvas used to directly contain the cursor; 
the new direct container is a descendant of this 
canvas. 




2 


The canvas used to indirectly contain the cursor; 
the new direct container is not a descendant of 
this canvas. 



A crossing event (either /EnterEvent or /ExitEvent) is generated for every 
affected canvas, although there is no requirement that such events match any 
interest. 

3,6. Input Synchronization Processing of input events is synchronized at the News process level inside the 

News server. This means that all events are distributed from a single queue, 
ordered by the time of occurrence of the event, and that when an event is taken 
from the head of the queue, all processes to which it is delivered are given a 
chance to run before the next event is taken from the queue. When an event is 
passed to redistributeevent, the event at the head of the event queue is not distri- 
buted until processes that receive the event in its redistribution have had a chance 
to process it. No event will be distributed before the time indicated in its 
TimeStamp. 

In some cases, a stricter guarantee of synchronization than this is required. For 
instance, suppose one process sees a mouse button go down and forks a new pro- 
cess to display and handle the menu until the corresponding button-up. The new 
process must be given a chance to express its interest before the button-up is 
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distributed, even if the user releases the button immediately. In general ^ 
ever processing of one event may affect the distribution policy, distributioii ^ 
the next event must be delayed until the policy change has been completed, 
is done with the blockinputqueue primitive. 

Execution of blockinputqueue prevents processing of any further events frc 
the event queue until a corresponding unblockinputqueue is executed, or a 
timeout has expired. The blockinputqueue primitive takes a numeric argur 
for the timeout; this is the fraction of a minute to wait before breaking the Ic 
This argument may also be null, in which case the default value is used 
(currently 0.0083333 == .5 second). Block/unblock pairs may nest; the que 
not released until the outermost unblock. When nested invocations of 
blockinputqueue are in effect, there is one timeout (the latest of the set assc 
ated with current blocks). 

Distribution of events returned to the system via redistributeevent is not 
affected by blockinputqueue, since those events are never returned to the e 
queue. 



3.7. Event Logging As an aid to developing News applications, there is a facility for monitoring 

distribution of events by the NeWS server. A process may be designated as t 
event’logger by a call to sete vent logger. This process will be given a copy 
every event as it is distributed by the NeWS server. This includes events as t 
are taken for distribution from the input queue, and also events handed to 
tributeevent. After having expressed some interest, the process shouldJ^o 
doing an awaitevent. 



The interest is required so that 
awaitevent doesn’t get a syntax 
error; it is not considered in the 
event-logging process. Therefore, it 
should not match any events; if it 
does, the process will receive two 
copies of those events. A -1 in the 
Name or Action is unlikely to match 
an event; an interest expressed on 
an unmapped canvas will also 
never match. 



That awaitevent will return a copy of each event as it is distributed. The p: 
may then do whatever it wishes with its copy; for example, it might print 
interesting fields in a window or a file. The file event log . ps described 
Chapter 4, Extensibility through POSTSCRIPT Language Files provides suet 
matted display of events. 

The current event-logging process, or null if there is none, is returned by a 
to geteventlogger. Event-logging may be turned off by passing null as the 
ment to seteventlogger. 
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3.8. Example The following short program illustrates many of the features of the News input 

system described in this chapter. It prints clock ticks on its standard output for 
15 seconds; then it prints a final message and goes away. 



r 




N 


/clock { 

{ 

/d 5 diet dup begin 
/Tick /Tock def 


% line 1 




/Tock /Tick def 
/Pumpkin { 

(Pumpkin time. ...\n) print 
exit 
} def 


% line 5 




end def 

/el createevent def 

e1 /Name d put 

e1 expressinterest 

/e2 e1 createevent copy def 


% line 10 




e2 begin 

/Name /Pumpkin def 
/Timestamp currenttime .25 add def 
end 

e2 sendevent 


% line 15 




/e3 e1 createevent copy def 
e3 dup begin 

/Name /Tock def 
/Timestamp currenttime def 
end { 


% line 20 




dup begin 

/Timestamp TimeStamp .016667 add def 
end sendevent 
awaitevent dup begin 
Name ( ) evs print 


% line 25 




(...\n) print 
end 
} loop 
} fork 
} def 

k . 


% line 30 


J 



In lines 3 - 10, the dictionary ‘d’ is defined to have three entries; ‘/Tick’ and 
‘/Tock’ are defined to each other, and ‘/Pumpkin’ is defined to be a small pro- 
cedure that prints a message and exits. 

This dictionary is then assigned to the /Name field of the event ‘e1,’ and ‘e1 ’ is 
passed to expressinterest (lines 12 and 13). This defines a class of events the 
‘clock’ process will accept and, incidentally, specifies some processing to be 
done as the events are received. The events that ‘eT will match fit the following 
criteria; 

□ The Name must be one of ‘/Tick,’ ‘/Tock,’ or ‘/Pumpkin’ (keys in the dic- 
tionary ‘d’ in the Name). 
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□ Any Action is valid (null in the Action). 

□ The location of the event doesn’t matter, but events directed to a specii 
canvas will not match (null in the Canvas). 

Because the Name in the interest is a dictionary, special processing is invol 
matching events. If the event Name is ‘/Tick’ or ‘/Tock,’ it will be translat 
the other as the event is matched. (Non-executable values in the dictionary 
replace the value in event field.) If the event Name is ‘/Pumpkin,’ it will r 
changed; rather, the value in ‘d’ of the procedure defined as ‘/Pumpkin’ wi 
executed as the awaitevent at line 28 returns. (Executable values in the die 
ary are queued for execution without changing the field in the event.) 

Line 14 creates the event ‘e2’ and initializes it to be the same as ‘e1 .’ Thi 
up the Name and Process of ‘e1 ’ (which was set by expressinterest); the i 
will be replaced, but the Process is used to direct ‘e2’ directly back to this 
cess. In lines 15-18, the Name of ‘e2’ is changed to ‘/Pumpkin’ and its 
TimeStamp is set to a quarter of a minute in the future. Then ‘e2’ is inset 
the event queue to be delivered when its time arrives (line 19). 

Lines 20 — 24 similarly create and initialize another event, ‘e3,’ and leave 
the stack for the main loop. The first part of the loop (lines 25 — 27) adds ' 
a minute to the TimeStamp of the event on the top of the stack (which is ‘ 
the first time through), and sends it back for distribution a second later. 

This leaves two events in the event queue which this process will be intere 
when they are eventually distributed: the short-term ‘Tick’ / ‘T ock’ re^^a 
which cycles every second, and the ‘/Pumpkin’ event waiting for 15 
expire. The awaitevent on line 28 will block until one or the other is deli 
If the event that arrives is one of the copies of ‘e3,’ its Name is translated 
matching process and printed in line 29 and the event is left on the stack fi 
another trip around the loop (and distribution cycle). When the ‘/Pumpki 
event finally arrives, its associated procedure executes as awaitevent retui 
minating the loop, and thus the ‘clock’ process. 
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Extensibility through POSTSCRIPT 

Language Files 



There is much more to producing a useful, full-featured window systems plat- 
form than the extensions to the POSTSCRIPT language described in the previous 
two chapters; an ideal server would provide some support for tailoring the user 
interface, selections between processes, the creation of windows and menus, etc. 

This is where the extensibility inherent in the POSTSCRIPT language and News 
has a tremendous impact. The NeWS server includes these extra features, but they 
are not “hard- wired” into the server; instead, they are provided as sets of 
PostScript language procedures in ASCII files that the server loads, usually 
when it starts up. 

You can look at these files, and are encouraged to do so: the files are in 
$NEWSHOME/lib/NeWS, where $NEWSHOME is the directory where you have 
mounted NeWS (usually /usr /NeWS). What is more, you can redefine or 
replace any of the procedures in those files, either globally when the server starts 
up, or within a single process. 

The next several chapters explain some of the facilities implemented in these 
files; this chapter gives an overview of them, and lists some of the miscellaneous 
procedures they define. 

4.1. Server Initialization When you start up the News server, its default initialization procedure (see the 

news_server(l) manual page) simply executes the POSTSCRIPT language in 
an ASCII file called init . ps and then runs the POSTSCRIPT language procedure 
‘&main' that init . ps defines (and which user . ps may have redefined), 
init . ps in turn loads other POSTSCRIPT language files. 

4.2. File Organization Here is an outline of the organization and contents of these POSTSCRIPT language 

files. 

PostScript language Files 
Loaded at Initialization 

init . ps Initializes the frame buffer; defines certain primitives in the POSTSCRIPT 

language rather than C; defines some “oughta-be” primitives such as case; 
defines and starts the server; sets certain constants and system defaults; loads 
most of the initialization files described here, init . ps also defines a default 
“root” menu” from which you can invoke common tools such as a terminal 
window and a clock. This rootmenu is one of the things you will probably want 
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systoklst .ps 

colors . ps 
cursor . ps 

statusdict .ps 

icon.ps 
util . ps 

litemenu . ps 
demomenu.ps 

litewin .ps 
liteUI . ps 



to redefine; see Appendix A, Using N^S, for tips on customizing your^^^-t 

A list of PostScript language primitives that are contained in the system c 
tionary systemdict. 

Implements the X.10V4 lib/rgb colors set. Adds the dictionary /Colordict t 
systemdict. 

Builds a dictionary useful for naming characters in cursorfont, a special fon 
cursors. Client-defined cursor fonts can also be built; see Chapter 16, Font 
Tools, for more information. 

Adds a statusdict to systemdict for users needing extreme printer compatil 
The file statusdict . ps implements the statusdict dictionary and its 
printer-specific operators such as printername and setsccbatch, as specific 
Section D.6 of the PostScript Language Reference Manual. Many of these 
operators are pseudo-implemented, since they have no meaning in a windo 
tern. 

Builds a dictionary useful for naming characters in iconfont. 

Procedures shared by packages; anything that is used by more than one pac 
should be defined in here. 

A menu package. 

Contains the demos that appear in the root menu. Some of these are run b} 
curing a UNIX program with forkunix; the code for other demos is part of 
POSTSCRIPT language file itself. 

A window manager package. 

Defines the user interface for NeWS. Runs several other * . ps files, which ; 
for selections (cutting and pasting), set up an input focus, and load the app 
ate translation table for your keyboard. 



PostScript language Files init . ps searches for these in the directory you started the NeWS server f 

for User Settings and failing that, looks in your home directory. Sample modifications to th 

given in Section A. 6 . 1 , Modifying theNMS Server. 



user . ps 



Private definitions and re-definitions of system and package POSTSCRIPT 
language words. 



startup .ps 



If startup . ps exists, init . ps will execute the POSTSCRIPT langua 
fragments in it before it loads any of the other packages. This lets you me 
characteristics of the server that are used before any of the other POSTSCR 
language files (including user .ps) are loaded; for example, verbose? i 
and the InitPaintRoot procedure which draws the background on ihe^^ 
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Other PostScript language 
Files 

compat .ps 

liteitem.ps 
litetext . ps 

debug.ps 
eventlog . ps 

journal.ps 

repeat .ps 

4.3, Some PostScript 
language Extensions in 
the * .ps Files 

Miscellaneous 



framebuffer while NeWS is loading. 

There are other files that define extensions to NeWS that are loaded by individual 
programs rather than by init . ps : 

Defines routines that make the server backwards-compatible with older NeWS 
client programs; in effect the server is programmed to emulate previous versions 
of the server. 

A simple item package used by itemdemo. 

A simple text package that is loaded by liteitem.ps; it also supports a 
blinking caret. 

PostScript language procedures used when debugging. 

A small package for monitoring input-event distribution, described under Section 
4.14, Logging Events below. 

A package for recording user actions and replaying them in "player-piano" mode, 
describe below under Section 4.9, Journalling Utilities, 

Implements variable-rate repeating on keyboard keys. Described under Section 
4.12, Repeating Keys below. 

Here are some of the more useful and commonly used POSTSCRIPT language pro- 
cedures in the * . ps files listed above. There are many more than are docu- 
mented here. These procedures are ultimately defined using POSTSCRIPT 
language operators described in the PostScript Language Reference Manual or in 
Chapter \2,NeWS Operator Extensions, of this manual. If these procedures don’t 
do quite what you want, look at their source and define your own versions. 

case and append are operations that nearly all PostScript programs need to 
perform, sprintf/printf/fprintf are near equivalents to their UNIX counterparts, 
arrayinsert, arraydelete and arrayop are useful operations on arrays, 
dictbegin/dictend save you from counting the size of dictionaries, modifyproc 
brackets a procedure, createcanvas is a quick way to create a canvas, sleep 
allows a PostScript language procedure to sleep for an arbitrary period, and 
getvalue and setvalue are useful for checking the status of an item, errored is 
very helpful for graceful error-handling. 
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case 



get value 



setvalue 



append 



sprintf 



printf 



value {key proc key key proc...} case - 

Compares value against several keys, performing the associated procectei-e i 
match is found. The key /Default matches all values. The following conve 
number to a (whimsical) string: 

MyNumber { 

1 {(One)} 

2 {(Two)} 

3 4 5 {(Between 3 & 5)} 

/Default {(Infinity)} 

} case 



- getvalue value 

Returns the ItemValue. The value depends on the nature of the object (e.g. 
a button, it is an boolean). 

value setvalue - 

Takes value and sets ItemValue to agree with it. Value is dependent on th 
nature of the object. 

ob]1 ob]2 append obj3 

Concatenates arrays, strings, and dictionaries. In case of duplicate dictions 
keys, the keys in the second dictionary overwrite the first’s. 

formatstring argarray sprintf string 

A utility similar to the standard C sprintf (3S). formatstring is a string 
'%’ characters where argument substitution is to occur. Thus: 

(Here is a string :%, and an integer:®/©) [(Hello) 1 0] sprintf 

puts the string 

(Here is a string:Hello, and an integer:! 0) 
on the stack. 

formatstring argarray printf - 

Printing form of sprintf. Prints on standard out, like print. 

See also: dbgprintf 
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fprintf 



arrayinsert 



arraydelete 



arrayop 



modifyproc 



createcanvas 



file formatstring argarray fprintf - 
Prints to file. For example: 

console (Server currenttime is:%n) [currenttime] fprintf 

will print the time the News server has been running on your console. 

See also: console 

array index value arrayinsert newarray 

Creates a new array one larger than the initial array by inserting value at position 
index. If index is beyond the end of the array value is appended to the end of the 
array. Thus: 

[/a /b /x /y] 2 0 arrayinsert => [/a /b 0 /x /y] 



array index arraydelete - 

Returns a new array, deleting the value in array at position index. If index is 
beyond the end of the array, the last item in the newly-constructed array is 
deleted. Thus: 

[/a /b 0 /x /y] 2 arraydelete => [/a /b /x /y] 

A B proc arrayop C 

Performs proc on pairs of elements from arrays A and B in turn, placing the result 
in array C. For example: 

[1 2 3] [4 5 6] {add} arrayop =>[5 7 9] 
proc head tail modifyproc {head proc tail} 

Adds a head and tail modification to a procedure. Mainly used to over-ride the 
behavior of a procedure. Thus: 

/myproc myproc {(myproc called\n) print} {} modifyproc store 

modifies the existing version of ‘myproc’ to print ‘myproc called’ each time it 
is invoked. 

NOTE Any of the procedures can be keywords. 

parentcanvas numx numy createcanvas canvas 

Creates canvas, a child of parentcanvas, located at (0, 0) relative to its parent and 
with the given width and height. 
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dictbegin 



dietend 



sleep 



errored 



4,4. User Interaction and 
Event Management 



getanimated 



- dictbegin - 

Combined with dietend, creates a dictionary “large enough” for subse(p»cfit 
and puts it on the dictionary stack. Avoids guessing what size dictionary to 
create. 

- dietend diet 

Returns the dictionary created by a previous dictbegin; together, they “shri 
wrap” a dictionary around your defs. Usage: 

/MyDict dictbegin 
/myvar 1 def 

dietend def 



interval sleep - 

sleep sends itself an event timestamped interval in the future, and returns w 
that event is delivered, interval is in minutes, with 1 6 bits of fraction. The 
usable resolution is about 10 milliseconds. 

any errored bool 

errored acts just like the stopped primitive, but for errors. Because this is 
erally what stopped has been used for, errored is recommended. 

Using errored also allows the debugger to work properly. Thus, if yoi 
currently using stopped as a way to detect errors, simply replace it with'eri 

The procedures getanimated, getclick, getrect, and getwholerect are used 
litewin . ps (and hence in most windowing applications) to let the user i 
cate window positions on the screen. You can use forkeventmgr and 
eventmgrinterest to handle forking an event manager that deals with partic 
events. Use setstandardcursor to set a canvas’s cursor to one of the stand 
News cursors. 



xO yO procedure getanimated process 

Forks a process that does animation while tracking the mouse, returning th< 
cess object process to the parent process. Each time the mouse moves, the 
cess executes ‘erasepage xO yO moveto,’ pushes the current mouse coon 
nates x and y onto its stack, and calls procedure. The variables xO, yO, x, ai 
are available to procedure. After procedure returns, the process executes tl 
stroke operator. Thus, your procedure can use xO, yO, x, and y to build a p; 
that will be drawn each time the mouse is moved — drawing a line to the c 
cursor location, for example. 

The process calling your procedure exits when the user clicks the mouse; i 
leaves the final mouse coordinates in an array ‘[x y]’ on top of its stack, so 
they are available to the parent process via the waitprocess operator. Sijjp 
erasepage is executed each time the mouse is moved, the current canv; 
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getclick 



getrect 



getwholerect 



forkeventmgr 



be an overlay canvas when you call getanimated, getanimated is used to imple- 
ment most rubber-banding operations on the screen such as in the rubber demo 
program. 

For example, the following code fragment animates a rubber band line that starts 
at (100,100) and returns the chosen endpoint: 

currentcanvas createoverlay setcanvas % Set current canvas to an overlay. 

1 00 1 00 { X y linetO } getanimated % Fork a process to track the mouse 

% and draw a line from 'xO, yO’ to it. 
waitprocess aload pop % Wait for the animation to complete, 

% then unpacks the returned 'x, y’ onto 
% the stack. 

This slightly more complicated version of the getanimated call prompts for a 
circle with its center at (100,100). The mouse controls its radius: 

100 100 { 

newpath xO yO 

X xO sub dup mul y yO sub dup mul add sqrt % Compute radius. 

0 360 arc 
} getanimated 

See also: createoverlay, waitprocess 

- getclick xO yO 

Uses getanimated to let the user indicate a point on the screen, getclick returns 
the location of the click on the stack. 

xO yO getrect process 

Uses getanimated to let the user “rubber-band” a rectangle with a fixed origin 
xO, yO. Returns a process with which you can retrieve the coordinates of the 
upper right-hand comer of the rectangle. Use waitprocess to put these coordi- 
nates [xl yl] on the stack. 

- getwholerect process 

Uses getclick and getrect to let the user indicate both the origin and a comer of a 
rectangle. Returns a process with which you can retrieve the coordinates of the 
both the origin and the upper right-hand comer of the rectangle. Use waitpro- 
cess to put these coordinates [xO yO xl yl] on the stack. 

interests forkeventmgr process 

Forks a process that expresses interest in interests, which may be either an array 
or a dictionary whose values are interests. Each interest must contain, in its 
/ClientData field, a dictionary having an entry (/proc) which is executed by the 
event manager process. This procedure is called with the event on the stack. 

NOTE The event manager uses some entries of the operand stack; do not use clear to 
clean up the stack in your 'proC' procedure. 
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eventmgrinterest eventname eventproc action canvas eventmgrinterest inteiJ*- ' 

Makes an interest. Suitable for use by forkeventmgr or expressintere^H^^ 
example: 

/MyEventMgr [ 

MenuButton {/popup MyMenu send} 

/DownTransition MyCanvas eventmgrinterest 
] forkeventmgr def 

will create an event manager that handles popping up a menu. 

setstandardcursor primary mask canvas setstandardcursor 

Sets canvas's cursor to the cursor composed of the primary and mask keyw 
primary and mask must be cursors in cursorfont, the font of standard systen 
sors loaded by cursor . ps. For example: 

/hourg /hourg_m MyCanvas setstandardcursor 

sets the cursor in ‘MyCanvas’ to an hourglass, usually to indicate that its p 
cess will not be responding to user input for a while. 

Here are the cursors (and their masks) in cursorfont: 

Table 4-1 Standard NMS Cursors 



Primary 

Image 


Mask 

Image 


Description 


WhenlWh^ 


ptr 


ptr_m 


arrow pointing to upper left 


default Wy 


beye 


beye_m 


bullseye 


window frame 


rtarr 


rtarr_m 


arrow 


menus 


xhair 


xhair_m 


crosshairs (“+” shape) 




xcurs 


xcurs_m 


“x” shape 


icons 


hourg 


hourg_m 


hourglass shape 


start-up/ canvas 


nouse 


nouse m 


no cursor 





See also: setcanvascursor 

4.5. Rectangle Utilities reel, reetpath, rect2points , rectsoverlap, and insetrect are useful for ma 

rectangular coordinates and paths; other graphics procedures are below urn 
Graphics Utilities. 

rect width height rect - 

Adds a rectangle to the current path at the current pen location. 
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rectpath 



rect2points 



pointsZrect 



rectsoverlap 



insetrect 



4.6. Graphics Utilities 



fillcanvas 



strokecanvas 



cshow 



rshow 



X y width height rectpath - 

Adds a rectangle to the current path with x,y as the origin. 

X y width height rect2points x y x’ y’ 

Converts a rectangle specified by its origin and size to a pair of points specifying 
the origin and top right comer of the rectangle. 

X y x’ y’ points2rect x y width height 

Converts a rectangle specified by any two opposite comers to one specified by an 
origin and size. 

X y w h x’ y’ w’ h’ rectsoverlap bool 

Returns tme if the two rectangles overlap. 

delta X y w h Insetrect x' y’ w’ h’ 

Creates a new rectangle inset by delta. 

The following are procedures often used to create graphics in canvases: fillcan- 
vas, strokecanvas, cshow, rshow, rectframe, ovalpath, ovalframe, rrectpath, 
rrectframe, and insetrrect. 



int/color fillcanvas - 

Fills the entire current canvas with the gray value or color, 

int/color strokecanvas - 

Strokes the border of the canvas with a one point edge with the gray value or 
color. Currently only works for rectangular canvases. 



String cshow - 

Shows string centered on the current location. 

String rshow - 

Shows string right-justified at the current location. 
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rectframe thickness x y w h rectframe - 

Creates a path composed of two rectangles, the first with origin x,y and Si-^c v 
the second inset from this by thickness. Calling eofill will fill the frame, whi 
stroke will create a “wire frame” around it. 



ovalpath 



X y w h ovalpath - 

Creates an oval path with the given bounding box. 



ovalframe 



thickness x y w h ovalframe - 

Similar to rectframe, but with an oval. 



rrectpath r x y w h rrectpath - 

Creates a rectangular path with rounded comers. The radius of the comer ar 
r, the bounding box i^xyw h. 

rrectframe thickness r x y w h rrectframe - 

Similar to rectframe, but with a rounded rectangle. 



insetrrect delta r x y w h insetrrect r’ x’ y’ w’ h’ 

Similar to insetrect, but with a rounded rectangle. 

4.7. CID Utilities There is a simple CID (Client IDentifier) synchronizer package availab^^i 

News utilities. It works by generating a unique identifier that is used to gen< 
a “channel” for talking to the client and receiving responses from the client; 
a synchronized manner. 

uniquedd - uniquecid integer 

Generates a unique identifier (integer) for use with the rest of the package. 



cidinterest 



DAMAGE_TAG is a client-defined 
tag, not a "standard" part of NeWS. 



id cidinterest interest 

Creates an interest appropriate for use with forkeventmgr. The callback pi 
cedure installed in this interest simply executes the code fragment stored in 
event’s /CiientData field. Typical use (in go demo): 



/repair { % - => - (repair the board) 

/MyCID uniquecid def 

DAMAGE_TAG tagprint MyCID typedprint 
[MyCID cidinterest] forkeventmgr 
waitprocess pop 

} def 



This procedure generates a unique id, then notifies the client to repair the (1 
aged board by sending over a DAMAGE_TAG and MyCID. It then fO|i^^ 
cess which listens for code fragments from the client to execute. The 
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waitprocess waits for one of these fragments to exit the forkeventmgr callback 
loop. 

sendcidevent id proc sendcidevent - 

Sends a code fragment to a process which was created by the cidinterest - 
forkeventmgr usage shown above. For example, the go demo uses the follow- 
ing to respond to the repair procedure above. These calls draw the go board, 
draw the black & white stones, erase a stone, and exit from the forkeventmgr 
callback loop. 




The id used is the one sent along with the DAMAGE_TAG. See Chapter 9, The 
C Client Interface for an explanation of the use of cdef. 



cidinterestlonly id cidinterestlonly interest 

A special form of cidinterest which processes only one code fragment. It 
automatically exits by itself, rather than requiring the client to send the exit. For 
example, the go demo uses this to respond to mouse buttons which place a single 
stone using the above drawing fragments. 

4,8. Text and Font Utilities The following utilities help you display and manipulate text: fontheight, fontas- 

cent, fontdescent, stringbbox, cvis, and cvas, findfilefont. 



fontheight font fontheight int 

Returns /(9/tr’s height. 

fontascent font fontascent int 

Returns font's ascent. 
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fontdescent font fontdescent int 

Returns /onr’s descent (as a positive number). 

stringbbox string stringbbox x y w h 

Returns string’s bounding box. 

cvis int cvis string 

Converts a (small) integer into a one-character string. 

cvas array cvas string 

Converts an array of (small) integers into a string. 

findfllefont String findfilefont font 

Reads the font family file named by the string and constructs and returns a foi 
object that refers to it. 

This is the way to have a bitmap The font will be entered into the FontDirectory under the fontname in the fatr 

font loaded into NeWS after it has 
started up. 

4.9. Journalling Utilities The following utilites allow you to control the journalling mechanism. With 

mechanism it is possible to to record and play back News user input events. 1 
file $NEWSHOME/lib/NeWS/ journal .ps implements the followinjiclar 
procedures: 

journalplay - journalplay - 

Begin replaying from the journalling file. The default filename is 
/tmp/NeWS . journal. 

journalrecord - journalrecord - 

Start a journalling session by oprening the journalling file and logging user 
actions to it. The default filename is /tmp/NeWS . journal. 

journalend - journalend - 

Ends a journalling session started by journalrecord and closes the joumallir 
file. 

Only raw mouse and keyboard events are replayed, so the system should be i 
the exacdy the same state at the beginning of the replay as it was at the start ( 
the journalling session — exactly the same windows in the same positions or 
screen, the same user running the system from the same directory, etc. jmirr 
play does take care of repositioning the mouse for you. 
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Journalling Internal Variables There are a number of internal variables that the journalling utilities use; 

□ RecordFile — the journalling file. 

□ PlayBackFile — same as RecordFile initially; this is the file from which 
playback will take place. 

□ PlaySpeed — multiplier for the base replay time speed. 

□ PlayForever — play forever if true. 

□ State — current state of journalling system. 

These variables are explained more fully in the comments of the file 
$NEWSHOME/ lib/NeWS/ journal .ps. They are defined in the News dic- 
tionary, journal. 

4.10. Constants The following are common constants, similar to #def ine’s in C: console, 

framebuffer, nullproc, nullstringand nulldict. 



console - console file 

Returns the file object for the system’s console. Use with fprintf to write mes- 
sages to the console. 

See also: fprintf 



framebuffer - framebuffer canvas 

Returns the root canvas. 

nullproc - nullproc procedure 

Returns a no-op procedure. 

nullstring - nullstring string 

Returns an empty string. 

nulldict - nulldict diet 

Returns an empty, small dictionary. 

4.11. Key Mapping Utilities A key may be bound to a procedure with the bindkey procedure. A key may be 

unbound using the unbindkey procedure. The following example binds the 
string ! make to key ( F8. 1 and assigns the NeWS — SunView selection converters 
to CHD and (TTUI ^: 



^ The ( FIO) function key doesn’t exist on Sun3 keyboards. 
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bindkey 



unbindkey 



4.12. Repeating Keys 



/FunctionFS { 


dup begin 




/Name /InsertValue def 
/Action (i.makeO def 




end 

redistributeevent 


} bindkey 




/FunctionF9 


(sv2newsjDut) bindkey 


/FunctionFlO 

L 


(news2sv_put) bindkey 


and the 1 F9 1 key may be unmapped with: 


/FunctionF9 unbindkey 



The following utilities allow you to bind keys: 

key arg bindkey - 

Creates a new process which watches for key to be depressed, and executes ( 
whenever that happens. If arg is an executable array, name, or string, it is si 
handed to the PostScript interpreter. Otherwise, if it is a string, then 

arg forkunix }’ 

is what gets evaluated. 

key arg unbindkey - 

Removes the binding of the arg for the specified key (there is no need to caf 
unbindkey before rebinding a key to a new value - the new value will repla 
old in bindkey). 



By default the standard typing array (not the function keys or shift keys) rej 
20 times per second, after a .5 second threshold. The repeating keys behavi 
implemented by a standalone repeat-keys package, 

$NEWSHOME/lib/NeWS /repeat . ps, loaded as part of the Extended Ii 
System started by init . ps. The threshold and repeat rate can be adjuster 
your preference by modifying two values in the User Profile dictionary; yoi 

put something like the following in your user . ps file to change them: 



UserProfile begin 

/KeyRepeatThresh 1 60 div 2 div def 
/KeyRepeatTime 1 60 div 1 2 div def 
end 

N 






microsystems 



Revision A of 15 Janua 




Chapter 4 — Extensibility through PostScript Language Files 45 



4A3. Colors Definitions ColorDict is a dictionary which contains named colors. It is implemented by 

colors.ps, which is loaded by init . ps. The color names are from the 
lib/rgb values in X.10V4. Here are some examples: 



r 

/Aquamarine 


112 219 147 RGBcolor del 


/MediumAquamarine 


50 204153 RGBcolor def 


/Black 


0 0 0 RGBcolor def 


/Blue 


0 0 255 RGBcolor def 


/CadetBlue 


95 159 159 RGBcolor def 


/CornflowerBlue 


66 66 111 RGBcolor def 


/DarkSlateBlue 




107 35 142 RGBcolor def 

- y 


. . . where RGBcolor simply converts 0 - 255 color values into NeWS colors: 




4.14. Logging Events The file event log . ps defines a procedure to turn logging of event distribution 

on and off, and a dictionary of events which should be excluded from the log. 
“Logging” means that a copy of each event is printed as it is taken out of the 
event queue for distribution. This is useful for debugging the server and clients 
using events heavily. It adds eventlog and UnloggedE vents to systemdict. The 
fields of the event which are printed are Serial#, TimeStamp, Location, Name, 
Action, Canvas, Process, KeyState, and ClientData. Here’s a sample log mes- 
sage: 

/"■ — - — — — — — ■ — - — ^ ^ — ■ — ^ 

#300 1.582 [166 161] EnterEvent 1 canvas ( 512x512 , root , parent ) null [] null 



UnloggedEvents This is a dictionary of event names which are considered uninteresting to an 

event whose Name is found in this dictionary will not be logged. The default 
definition of UnloggedEvents is 
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The Extended Input System 



The input mechanisms described thus far provide two things: 

□ a basic, default user interface, and 

□ a platform on which to build more sophisticated interfaces, such as 
SunView’s. 

The default interface provides a simple ASCII keyboard: characters are delivered 
when a key goes down; there is no way to be notified when a key goes up, or 
what the state of non-character shift keys is ( 1 Control I [ Shift 1 ). Characters are 
delivered to the last process to express a global interest in ±em, or to the canvas 
under the cursor if there is no global interest. Interfaces that use the mouse are 
responsible for doing their own mouse tracking and interpretation. 

5.1. Building on NeWS Input This chapter describes an Extended Input System (EIS). It is implemented 
Facilities entirely in the POSTSCRIPT language, on top of the basic facilities provided by 

the primitives in the NeWS server. It aims to support a sophisticated interface of 
at least the complexity of SunView or the Mac, and to provide at least one such 
interface as an existence proof. It also is aimed at separating independent issues 
in the implementation of interfaces. For example, it should be possible to pro- 
vide alternatives in each of the following three categories without dependencies 
between categories and without requiring any change to client code: 

□ different input devices (1- and 3-button mice, or keyboards with different 
collections of function keys); 

□ alternative styles of input-focus, such as follow-cursor or click-to-type; 

□ alternative styles of selection, such as point-and-extend or wipe-through. 

The EIS is sufficiently flexible that it should be possible to support a keyboard- 
only input system. 

This chapter has several independent sections, corresponding to some of the 
modules of the EIS. It begins with a description of a particular user interface, 
implemented by the file liteUI . ps, which is a suggestive subset of the Sun- 
View interface. It includes a description of the requirements and facilities for a 
client to handle keyboard input and selections in that world. 

A good deal of the processing in the EIS is carried on in a single process called 
“the global input handler.” Some of it, however, must be done on a per-client 
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basis; facilities are provided which are active in the client’s lightweig^^ 
in the server. For example, recognizing events that indicate a change 
focus and distributing keystrokes to that focus are done in the global input 
handler. But recognizing user actions that indicate a selection is to be mad 
be done for each client, since some clients will not make selections at all, t 
apply other interpretations to the same user actions. 

5.2. The LiteUI Interface The liteUI implementation provides distribution of keyboard input and ma: 

ment of selections in a style reminiscent of SunView. 

Primary, Secondary, and Shelve selections are provided; Put and Get work 
all of them in the standard fashion. Selections are made when the mouse b 
goes down, and are always in character units. Keyboard focus may be con 
either by cursor motion into and out of windows, or by clicking a mouse bi 
to reset the focus. In the latter mode, the Point button sets both the focus ^ 
Primary selection at the indicated position; the Adjust button restores the f 
a window, at its previous position, and without affecting the Primary selec 

There is no multi-clicking to grow a selection, and no dragging a selection 
the button down. The Find and Delete functions do not yet have any clien 
so they have not been implemented. These restrictions are simply things r 
(yet) done in liteUI; the underlying facilities to support them are already ii 
EIS. 

Clients of the liteUI interface are all lightweight processes running in the r 
server. Such clients may have two categories of interaction with litelM^.i 
keyboard input, and dealing with selections (for example, cutting ano^^t 
between windows). In general, a client follows the sequence: 

□ In an initialization phase, the client declares its interest in various clai 
activity. These classes include simple and extended keyboard input, < 
selection processing. In response, the EIS sets up a number of interes 
(some in the global input handler, some in the client’s own process), j 
records the client in some global structures. 

□ The client process enters its main loop, which includes an awaitevent 
of the events it receives will be in response to interests expressed in tl 
tialization calls it made. These events will generally be at a high sem 
level; translating mouse events into selection actions is done inside E 
The client will typically have more work to do with these events; for 
pie, characters may be sent across the communication channel to be p 
cessed in the client’s non-POSTSCRIPT language code. Some of the p 
ing will require calls back into EIS code; for example, a client will h^ 
inform the system what selection it has made in response to selection 

□ Finally, when a client no longer requires various EIS facilities, it sho 
revoke its interests, so that resources do not remain committed when 
longer needs them. 
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5.3. Keyboard Input 

Keyboard Input: Simple 
ASCn Characters 



addkbdinterests 



Four procedures provide access to increasingly sophisticated levels of keyboard 
input. The most straightforward client merely wants to get characters from the 
keyboard. This is done by invoking addkbdinterests (passing the client canvas 
as an argument) and then sitting in a loop, doing an awaitevent and processing 
the returned event. 

canvas addkbdinterests [events] 

declares the client as a candidate for the input focus. It also creates and expresses 
interest in the following three kinds of events, and returns an array of the three 
corresponding interest-events: 

The first interest has ascii_keymap for its Name, and /DownTransition for its 
Action. (ascii_keymap is a dictionary provided by EIS forexpressing interest in 
ASCII characters; it includes the translation from the user’s keyboard to the ASCII 
character codes where that is necessary.) Events which match this interest will 
have ASCII characters in their Names, and /DownTransition in their actions. 

The client can choose to see up-events too, by storing null into the Action field 
of this interest. 

The second interest has /InsertValue and a null Action. This will match events 
whose Name is the keyword /InsertValue, and whose Action is a string which is 
to be treated as though it had been typed by the user. Such events will be gen- 
erated if some process is doing selection-pasting to this window, or if function- 
key strings have also been requested (see below). 

The third interest has the array [ /AcceptFocus /RestoreFocus /DeSelect ] in its 
Name. Events matching this interest inform the client it has gotten or lost the 
input focus. (/Deselect events referring to the focus will have an Action of 
/InputFocus; clients doing selection processing may also receive /DeSelect 
events for other objects besides the input focus, as described below under 5e/ec- 
tion Events.) These events are informational only; they do not affect the distribu- 
tion of keyboard events. They are intended for clients which provide some feed- 
back, such as a modified namestripe or a blinking caret, when they have the 
focus. Clients are always free to ignore them. 

A process that is about to exit, or that will continue to exist, but wants no more 
keyboard input, may revoke an interest in keyboard input by passing the array 
returned from addkbdinterests, along with the client canvas, to revokekbdin- 
terests; 
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[events] canvas revokekbdinterests - 

Undoes all the effects of addkbdinterests. 

By default, clients do not receive any events associated with function keys, 
client can choose to receive function-key events, either in the form of a key' 
naming the key that went down, or as a string of the form "ESC [ nnnz” (th 
ASCII-standard escape sequence for such keys). 

To get the function-keys identified by escape sequences, the client should p; 
client canvas to addfunctionstringsinterest. 

canvas addfunctionstringsinterest event 

creates an interest in tlie function keys, expresses interest in it, and returns t 
event. As a result, when a function key is depressed, awaitevent returns an 
whose Name is /Insert Value, and whose Action is a string holding the esc; 
sequence defined for that key. Only function-key-down events can be recei 
by this mechanism. Addkbdinterests must also have been called for this p 
cedure to have any effect. 

To get the function-keys identified by name, the client should pass its clien 
vas to addfunctionnamesinterest. 

canvas addfunctionnamesinterest event 

creates an interest in the function keys, expresses interest in it, and rety s i 
event. As a result, when a function key is pressed, awaitevent retumsSt-i 
whose Name is a keyword like /FunctionLT. By default, both up and dow 
sitions on the keys are noted; the client may change this by storing /Downi 
sition (or /UpTransition, if that is what is desired) into the Action field of 
returned interest. Addkbdinterests must also have been called for this pro 
to have any effect. 

No special procedure is provided to revoke interests generated by either of 
two procedures, since passing the interest to the revokeinterest primitive 
suffices. 

Assigning Function Keys You may assign a given procedure to be executed when a specified key go( 

down. See the section on bindef in Chapter 4, Extensibility through POSTS 
language Files. 

Keyboard Editing and Cursor If the client is passing characters through to a shell or some similar process 

Control will do its own translations on them, they should be passed unmodified. B 

the client is dealing with text directly, it should provide the editing and cat 
motion facilities defined in the user’s global profile. To assist in this, the c 
may ask for incoming events to be checked for a match against those keyb 
actions, and converted to uniform editing-events if they do. This is done b 
ing the client canvas to addeditkeysinterest. 



revokekbdinterests 



Keyboard Input: Function 
Keys 



addfunctionstringsinterest 



addfunctionnamesinterest 
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addeditkeysinterest 



5.4. Selection Overview 
and Data Structures 



canvas addeditkeysinterest event 

creates an interest in the key combinations that are defined for global editing and 
caret motion, expresses interest in it, and returns that event. As a result, the 
client sees events with a Name from the set: 

{Edit,Move}{Back,Fwd}{Char,Word,Field,Line,Column} 

For example, here are the key combinations for EditBack*: 

EditBackChar null 

delete the character before the caret 

EditBackWord null 

delete the word before the caret 

EditBackField null 

move the caret back to the end of the preceding field if any exists, 
deleting its contents or selecting them in pending-delete mode 

EditBackLine null 

delete from the caret back to the beginning of the current line 

EditBackColumn null 

delete all characters between the caret and the nearest boundary in 
the line above; if the previous line ends to the left of the caret, 
delete back through the preceding end-of-line 

Substituting Fwd for Back indicates the deletion or motion (see the next para- 
graph) extends after rather than before the caret. EditFwdLine deletes through 
the next end-of-line. 

Substituting Move for Edit indicates the caret is moved to the far end of the span 
that would be deleted by an Edit, but the characters are not deleted. 

Again, no separate procedure is provided to revoke this interest, since the 
revokeinterest primitive does exactly what is needed. 

Clients that will make selections and pass information about them to other 
processes declare this interest via addseiectioninterests. Thereafter, EIS code 
will process user inputs according to the current selection policy. Occasionally, 
it will pass a higher-level event through to the client, when some client action is 
required in response. The exact interface by which a user indicates a selection is 
not the client’s responsibility; the client must simply be prepared to handle 
higher-level events. Clients will also occasionally see events with a Name of 
/Ignore; these are events which were delivered to the client process, but handled 
entirely by EIS code before the event was made available to the client. The 
/Ignore event is left behind in this situation so that client code can depend on an 
event being on the stack when it gets control after awaitevent returns. 
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Selection Data Structures There is no separate “selection service” in EIS; some selection proces^^ 

place in the global input handler, and the rest in client processes. Ther^is"^ a 
bal repository of data about selections, however, and there are some standai 
mats for the information stored in that repository and communicated betwe( 
selection clients. 

A selection is named by its rank\ in liteUI, the ranks are /PrimarySelectior 
/SecondarySelection, and/ShelveSelection^. For each rank, there is a diet 
ary containing the information known to the system about that selection. S 
dictionary will be called a selection-dict henceforth. It will have at least th< 
lowing three keys defined: 

Table 5-1 Selection-Diet Keys 



Key 


Type 


Semantics 


/SelectionHolder 


process 


which process made the selecti( 


/Canvas 


canvas 


the canvas in which the selectic 
was made 


/SelectionResponder 


null 1 process 


what process will answer reque 
concerning this selection 



If /SelectionResponder is defined to null, there will be other keys defined 
dictionary, setting out all available information about that selection. A fev 
keys have been defined because they are expected to be generally useful. T 
are listed in the table below. Others may be provided by clients as con^a: 
there is no limit on what consenting clients may say to each other abo\fe_/s 
tion. 

Table 5-2 System-defined Selection Attributes 



Key 


Type 


Semantics 


/ContentsAscii 


string 


selection contents, encoded as a strii 


/ContentsPostScript 


string 


selection contents, encoded as an 
executable POSTSCRIPT language ot 


/ SelectionObj size 


number 


n >= 0; for text, 1 indicates a charac 


/SelectionStartIndex 


number 


position of the first object of selectic 
in its container 


/SelectionLastIndex 


number 


position of the last object of selectic 
in its container 



Finally, communications between clients about selections (that is, request: 
their responses) are formatted as another dictionary, hereafter called a req^ 
diet. When submitted by the requester, the dictionary will have a key nan 
each attribute it wants the value of. (It may also contain commands the se 
holder should execute, such as /ReplaceContents.) When received by a s 
tion holder, a request-diet will contain the keys defined by ihe requester, f 

^ There is nothing to prevent clients from using other ranks, with names they define themselves. S 
speaking a rank is simply a key in the Selections dictionary. 
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Selections: Library 
Procedures 

addselectioninterests 



clearselection 

selectionrequest 



following two: 

Table 5-3 Request-diet Entries 



Key 


Type 


Semantics 


/Rank 

/SelectionRequester 


rank 

process 


the rank selection this request concerns 
the process which is sending the request 



The use of these various structures is detailed under the relevant event descrip- 
tions below. 

This section lists the library procedures provided for clients to deal with selec- 
tions. 

canvas addselectioninterests [events] 

creates and expresses interest in two classes of events, returning an array of the 
two interests. 

The first interest matches events with names in the following list: 

/InsertValue 

/SetSelectionAt 

/ExtendSelectionTo 

/Deselect 

/ShelveSelection 

/SelectionRequest 

The response required from the client to each of these events is detailed below 
under Selection Events, (Some clients may safely omit handlers for the last two; 
see the detailed description). 

The second interest matches events which are uninteresting to the client. It 
arranges for EIS processing to be done by library code before the client ever sees 
the event. 

rank clearselection - 

sets the indicated selection to null; this allows a selection holder to indicate the 
selection no longer exists. 



request-diet rank selectionrequest request-diet 
sends a request (contained in request-diet) concerning the rank selection. The 
format of a request-diet is described above, in Table 5-3, Request-diet Entries. 
The /SelectionRequester and /Rank entries will be filled in by selectionrequest, 
which will process the request and return a response. If the indicated selection 
does not exist, null will be returned. Some keys in the request may not have an 
answer available. In this case they will be defined to /UnknownRequest in the 
response. 
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selectionresponse 



setselection 



getselection 



Selection Events 



event selectionresponse - 

is used by a selection holder to return a response to a selection request.'^.:'!{e 
argument should be a /SelectionRequest event that has been processed by t 
holder. (/SelectionRequest events are described below under Selection Eve 
The event will be transformed into a /SelectionResponse event and retumei 
the requester. 

selection-dict rank setselection - 

is used by a process to declare itself the holder of a selection. Selection-dic 
dictionary containing either a definition of /SelectionResponder, or of key: 
which provide data about the selection itself, as described above in Table 5 
Selection Data Structures. Rank indicates which selection is being set. If 
another process currently holds that selection, it will be told to deselect. 



rank getselection selection-dict 

retrieves the information currently known to the system about the indicated 
selection. This procedure is likely to be more useful to the implementor of 
package like liteUI than to window clients. 



As mentioned above, clients may expect to receive six different kinds of e\ 
concerning the selection. Of these, the InsertValue event has already beer 
described under Keyboard Input, its usage in the selection context is exggtl 
same as for function strings. The remaining five events and the approf^yj 
responses to them are presented below. 

Each event is described in the following format: 



EventType short description of the event’s semantics 



Name: 

keyword that identifies the event 

Action: 

description of the contents of the event’ s 

Action 



Response: 

description of what the client should do 
when it receives such an event 
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/SetSelectionAt 



Informs the client the user has just made a selection in its canvas. 
Name; 

/SetSelectionAt 



Action: 

diet [ 



] 



Rank 

X 

Y 

PendingDelete 

Preview 

Size 



/PrimarySelection | /SecondarySelection 

number 

number 

true I false 

true I false 

number 



NOTE LiteUI provides constant values for three fields: PendingDelete = false, Preview 
= false, and Size = 1 . 

Response; 



Make a selection of the indicated Rank with the following parameters: 



Key 


Value 


XandY 


indicate a position (it will be in the current canvas’ 
coordinate system). 


Size 


indicates the unit to be selected; for example, in text: 

0 means a null selection at the nearest character 
boundary, 

1 corresponds to a character, and 

larger values indicate larger units (words, lines, etc.) 
whose definition is at the discretion of the client 


PendingDelete 


indicates whether that mode should be used 
(if supported by the client) 


Preview 


indicates whether the selection is only for feedback to 
the user; a selection shouldn’t actually be set until 
a selection event is received with Preview false 



In client POSTSCRIPT language code, some private processing will generally 
be required. For instance, the given position will have to be resolved to a 
character in a text window, and appropriate feedback displayed on the 
screen. Then the client should build a selection-dict describing the selection 
just made, and pass it to setselection, along with the rank it received in the 
/SetSelectionAt event: 

selection-dict rank setselection 

Selection-dict should contain either a non- null definition of /Selection- 
Responder, or it should define keys which actually provide information 
about the selection (/ContentsAscii at a minimum). In the former case, the 
holder is following a communication-model of selection, and must be 
prepared to receive and respond to /SelectionRequest events as long as it 
holds the selection. In the latter case, the holder is following a buffer-model 
of selection; requests will be answered automatically by the global input 
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ExtendSelectionTo 



Deselect 



handler. 

Selection-dict will have keys added to it, so it should be created with roc 
for at least five more entries beyond those defined by the client. 

Informs the client the user has just adjusted the bounds of a selection in its c; 
vas. 

Name: 

/ExtendSelectionTo 

Action: 



diet [ 


Rank 


/PrimarySelection | /SecondarySe 




X 


number 




Y 


number 




PendingDelete 


true 1 false 




Preview 


true 1 false 


] 


Size 


number 


Response: 






The dictionary in the Action field 


is the same as the Action of a /SetSe 



tionAt event, and the client response is very much the same. The distir 
is that this event indicates a modification of an existing selection, where 
/SetSelectionAt indicates a new one. 

The client should adjust the nearest end of the current selection of 
cated Rank to include the indicated position. If Size indicates growth, 
extend both ends as necessary to get them at a boundary of the indicatei 
size. (For example, if Size has changed from 1 to 2, a text window mig 
grow both ends of the selection to ensure that they fall at word boundar 
Adjust the PendihgDelete mode or ignore it as the window is editable ( 
not. 

If there was no selection of the indicated rank, pretend there was an em 
one at the indicated position. 

In client POSTSCRIPT language code, after doing any private processing 
required, processing is exactly the same as for /SetSelectionAt. 

Informs the client that it no longer holds the indicated selection. 

Name: 

/Deselect 

Action: 

rank 

Response: 

Undo a selection of the given rank in this window. Do not call 
clearselection; the global selection information has already been updal 
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ShelveSelection 



SelectionRequest 



5.5. Input Focus 



Tells the client to set the shelf selection to be the same as a selection which the 
client currently holds. 

Name: 

/ShelveSelection 

Action: 

rank 

Response: 

Buffer-model clients (those that did not define /SelectionResponder when 
they set the selection) will not receive ShelveSelection events; the service 
will copy their selection to the shelf for them. Others should set the Shel- 
veSelection to be the same as the selection whose rank is in Action, using 
setselection as above. 

The client is requested to provide information about a selection it holds. 

Name: 

/SelectionRequest 

Action: 

request-diet 

Response: 

Buffer-model clients (those that did not define /SelectionResponder when 
they set the selection) will not receive SelectionRequest events; the service 
will answer the request for them. 

The client should enumerate the request-diet, responding to the various 
requests by defining their values (as for /ContentsAscii), or performing the 
requested operation (as for/ReplaceContents, whose value will be the 
replacement value). The resultant diet should be left as the Action of the 
event, which should then be passed as the argument to the procedure selec- 
tionresponse. 

NOTE There is no restriction on what requests may be contained in a selection request; 
this is left to negotiation between the requester and the selection holder. A 
holder may reject any request, by defining its value to be /Unknov/nRequest. 

It may be noted that there is no mechanism described here for getting a 
selection’s contents from someplace else. In liteUI, user actions that precipitate 
such a transfer are recognized and processed in the global input handler, which 
then performs the selection request, and sends an /InsertValue event to the 
receiving process. The selection library procedures described above provide an 
interface for instigating such transfers independent of user actions. 

The input focus (where standard keyboard events are directed) is maintained by 
the global input-handler process, according to the current focus policy. A client 
becomes eligible to be the input focus by calling addkbdinterests (described 
above und&r Selections: Library Procedures). At some later time, some user 
action will indicate that the client should become the focus. The client will 
receive an event indicating this has happened (its Name will be /AcceptFocus or 



Asun 



microsystems 



Revision A of 15 January 1988 




60 News 1.1 Manual 



setinputfocus 



currentinputfocus 



hasfocus 



setfocusmode 



/RestoreFocus, and its Action will be null). Thereafter, the client wil^ 
events whose Names are ASCII character codes. ^ " 

This section describes a collection of routines provided to inquire about anc 
manipulate the focus. These normally will not be called by clients of the w 
system; rather, they support focus-policy implementations, which then com 
cate with the clients. 

The focus is identified in an array with two elements, a canvas and a proces 
The canvas will be the canvas argument to addkbdinterests. The process ' 
be one which called addkbdinterests, and which should be doing an await 
for keyboard events. 

canvas process setinputfocus - 

The input focus is set to be the canvas - client pair identified by the argumt 
setinputfocus. 

- currentinputfocus [canvas, process] 

The current input focus is returned by currentinputfocus. If there is no cu 
focus, null is returned. 

process hasfocus bool 

Returns true or false as the indicated process is or is not currently the inpu 
focus. 

keyword setfocusmode - 

The global focus policy is reset to the policy named by the argument. 
Currently-supported focus policies are identified by: 

/ClickFocus 

As long as no function keys are down clicking the Select button will s 
the focus and the primary selection in a window. Clicking Adjust will 
the focus at its last position in this window, without making any selec 

/CursorFocus 

a window will receive the focus when the mouse enters its subtree, an 
it when the mouse exits. If the mouse crosses window boundaries wh 
function key is down, a focus change is delayed until all function key: 
up, and then reflects the current situation. 

/DefauItFocus 

events are distributed as though no EIS were in effect. 
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6 



Classes 



The reader familiar with traditional window systems will have noticed no men- 
tion of menus, windows, scrollbars, and the like. This is intentional; News pro- 
vides xht facilities to build these higher-level user interface tools without impos- 
ing its notion of what these tools must be. Think of News as providing the win- 
dow management “kernel” from which a user interface toolkit may easily be 
made. 

On the other hand, there is a need to provide some user-interface tools. Our solu- 
tion is to provide a small set of user interface packages, written entirely in the 
PostScript language, which you may use as a base for more sophisticated 
development. 

These are implemented using an object-oriented programming^ scheme that is 
quite similar to Smalltalk.*^ This scheme has several advantages: 

□ It is a well-documented standard discussed in several easily obtainable 
books. 

□ It is easily and naturally mapped onto the POSTSCRIPT language. 

□ It formalizes the flexibility and modularity available through use of the 
PostScript language dictionaries. 

□ There are at least two well -documented class hierarchies for application 
writing: Smalltalk itself, and MacApp^ Apple’s “extensible application.” 

This chapter discusses News’s implementation of Smalltalk’s class mechanism. 
The following chapter. Window and Menu Packages, presents two packages, 
menus and windows, built using this class mechanism. Appendix B, Class 
Liteltem, describes the implementation of a demonstration item class using 
class-based programming. Some of this information was presented in a tutorial 
given at the Winter 1986 USENIX Graphics Workshop.^ 

6.1. Packages and Classes The reader unfamiliar with message-passing, classes, and object-oriented pro- 
gramming might like to browse through the references listed at the end of the 
chapter. However, many of the essential ideas in class-based systems are similar 
to the more traditional “package”- or “module”-based systems. 
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Briefly: 

□ Packages (modules) are replaced by classes. 

□ Procedures in packages are replaced by methods in classes. 

□ Creating package objects is replaced by creating new instances of a cla‘ 

□ Package local and global variables are replaced by class variables. 

□ Object variables are replaced by instance variables. 

New notions are: 

□ Classes are ordered into a hierarchy by subclassing a new class to a pri( 
one, inheriting its methods, instance variables, and class variables. 

□ Methods are invoked by use of the send primitive. The term message 
used for an invocation of a method with its arguments. 

□ There is a means of constructing classes that is absent in most language 
module creation. 



Note: self does not refer to the 
method’s class, but rather the 
object that originally caused the 
method to be invoked. If the 
method is inherited, self will not be 
the method’s class, for example. 



□ Two new concepts, the self 2ind super pseudo-variables, are introduced 
They are used in methods to refer to the object that sent the message ai 
method’s superclass, respectively. 

□ Unlike POSTSCRIIT language procedures, methods are compiled when 
class is created. Currently this simply resolves self and super, and peri 
some minor optimizations. 



The relationship between an instance and its class and superclass is shown 
figure below. We have made an instance, ‘aFoo,’ of class ‘Foo,’ which is 
class of class Object. An instance has a copy of all instance variables of it: 
superclasses, thus ‘aFoo’ has those required by both ‘Foo’ and Object. T1 
methods known by an instance are stored in the classes in its superclass chi 
Thus ‘aFoo’ can only respond to methods residing in ‘Foo’ and Object. 



aFoo 



Foo 



Object 











null 










instance 




class 




class 


variables 




variables 




variables 






& 




& 






methods 




methods 



instance 



class 



class 



Figure 6-1 Relationship between Instances and Classes 

Sending a message to an instance requires packaging the arguments to the 
method, finding the method in the class chain, invoking the method in the 
context, and possibly returning a result to the sender. If the pseudo-variab 
is used for the object in sending a message, the search for the method start: 
beginning of the chain, while if super is used the search starts in the si 
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Figure 6-2 Self and Super 

6.2. Introduction to Classes The PostScript language implementation of classes uses dictionaries to 

represent the classes and instances. Instances contain all the instance variables of 
all their superclasses. Classes contain their methods as POSTSCRIPT language 
procedures. Our current implementation of class is entirely in the POSTSCRIPT 
language. 




Figure 6-3 POSTSCRIPT language use of Dictionaries as Objects 

Classes are built using the classbegin . . . classend procedures; messages are sent 
with the send primitive: 

classbegin classname superclass instancevariables classbegin - 

Creates an empty class dictionary that is a subclass of superclass, and has instan- 
cevariables associated with each instance of this class. The dictionary is put on 
the diet stack. Instancevariables may be either an array of keywords, in which 
case they are initialized to null, or a dictionary, in which case they are initialized 
to the values in the dictionary. 
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dassend 



send 



self 



super 



- dassend classname diet 

Pops the current diet off the diet stack (put on by classbegin and presudfaol; 
filled in by subsequent defs), and turns it into a true class dictionary. This 
involves compiling the methods and building various data stmetures comme 
all classes. 



<optional args> method object send <optional results> 
Establishes the object’s context by putting it and its class hierarchy on the d 
tionary stack, executes the method, then restores the initial context. The me 
is typically the keyword of a method in the class of the object, but it can be 
arbitrary procedure. (See the examples below.) 



userdict 

systemdict 
dictstack [before] 



argl arg2 /meth aFoo send 



aFoo 

Foo 

Object 

userdict 

systemdict 
dictstack [after] 



Figure 6-4 POSTSCRIPT language use of Dictionaries as Objects 



- self instance 

Used as the target object with send, self refers to the instance that caused th 
current method to be invoked. It does not refer to the class the method is de 
in. In Figure 6-2, Self and Super, the method ‘ob]1 ’ in class Object uses sc 
refer to ‘aFoo,’ not Object. The self primitive can also be used anywhere i 
refer to the currently active instance. 



- super instance 

Used as the target object with send, super refers to the method being oveni 
by the current method. In the figure above, the method ‘foot ’ in class ‘Foc 
overrides the method ‘fool ’ in Object. The use of super in ‘fool ’ refers tc 
overridden method. Unlike self, super cannot be used outside the context c 
send. 

Here is the creation of the class Object, the root class of all classes: 
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/Object null [] classbegin 
% class variables 
% methods 

/new { % class => instance (make a new object) 

} def 

/doit { % proc ins => - (compile & execute the proc) 

} def 

classend def 

It is simple indeed, having no instance or class variables, and only two methods 
at this writing. They are important, however, because they are shared by all 
classes, /new builds an instance of a class. If you need to override /new to do 
something unique for your class, you would first call /new super send to have 
your superclasses do their thing; then modify the object you receive. (See the 
sample below.) /doit is used to create a temporary method and execute it in the 
context of the object. This is generally only required if the procedure contains 
the pseudo-variables self or super. 

/new may be sent to instances as well as classes. The /new method is 
polymorphic. Exactly the same result is obtained if you send /new to a class or an 
instance of that class. 

The /new method in class Object notices that "self is an instance rather than a 
class, and send the message on to its class. This can be a very useful way of 
creating a new object without knowing its class. 

6.3. Class ‘Foo’ Now lets build a sample class, ‘Foo’: 
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% ‘Foo’ is a subclass of Object 
% (initialized) instance variables 



% The class variable ‘ClassTime’ 
% - => - (Make a new ‘Foo’ j 



% — => - (Print current state) 

•\n) [Value Time] printf 
% value => - (Change the value of ‘Value 

% — => - (Change ‘Time’ to the current U 



‘Foo’ is a subclass of Object, as discussed above. ‘Foo’ has two instance \ 
ables unique to each of its objects; ‘Value,’ an arbitrary value associated wi 
object, and ‘Time,’ the time of creation of the object. They are initialized b 
of the diet form of specifying instance variables. (The dietbegin . . . dictem 
are standard utilities that create a diet just the right size for its defs.) Foo h 
one class variable, ‘ClassTime,’ which is the time of creation of the class. 

‘Foo’ has four methods: ‘new,’ ‘printvars,’ ‘changevalue,’ and ‘resettim 
‘new’ first calls its super class to get a raw instance, which it then initializes 
setting the time to the current time. Note the use of begin . . . currentdict e 
This is a s “cliche'.” Also note the use of both self and super; we ask our s 
class to make a new instance of itself and initialize it, then ask self to reset c 
time, ‘printvars’ is used to print the instance and class variables of the obje 
note how this uses another standard utility, printf. ‘changevalue’ is a met 
that takes a single argument and assigns it to the instance variable ‘value.’ 
Finally, ‘resettime’ sets the instance variable ‘time’ to the current time. 

Let’s look at some uses of ‘Foo.’ Here we create a new instance, ‘fOO’ of ‘I 
We then print out its initial values, shown by the line starting with “...we g( 
(By the way, we’re getting these examples by cutting and pasting into a win 
running psh onto ourNeWS server.) 



/Foo Object 
dietbegin 

/Value 0 def 
/Time null def 
dictend 
classbegin 

/ClassTime currenttime def 

% class methods 
/new { 

/new super send begin 
/resettime self send 
currentdict 
end 
}def 

/printvars { 

(...we got: Value=%, Time=% 
}def 

/changevalue { 

/Value exch def 
}def 

/resettime { 

/Time currenttime def 
} def 

classend def 
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/foo /new Foo send def 

/printvars foo send 

...we got: Value=0, Time=22.8837. 

Now we are going to change the value of ‘foo’s instance variable ‘Value.’ Note 
that it initially was an integer, and we are changing it to a string; this is an exam- 
ple of PostScript language “polymorphism.” 

(A String) /changevalue foo send 
/printvars foo send 

...we got; Value=A String, Time=22.8837. 

Similarly, this resets the time value of ‘foo.’ 

/resettime foo send 
/printvars foo send 

...we got: Value=A String, Time=23.1963. 

Now we do an odd thing, we simply send an executable array (a procedure) to 
‘foo.’ The effect of doing this is to execute the procedure within the context of 
‘foo.’ (This is somewhat unfair, like cutting paper in Origami, but nicely illus- 
trates the flavor of our combination of POSTSCRIPT language features and our 
class extensions.) The procedure we’re sending to ‘too’ is {/Time ClassTime 
def}, which assigns ‘ClassTime,’ the class variable, to ‘Time,’ the instance vari- 
able. 

{/Time ClassTime def} foo send 
/printvars foo send 

...we got: Value=A String, Time=22.7444. 

The above sample did not go through method compilation, thus self and super 
could not be used. Let’s send an executable to ‘foo’ to change ‘Value’ to the 
number of minutes since its creation, but this time using the more orthodox doit 
method (it uses method compilation). 

(currenttime Time sub round /changevalue self send} /doit foo send 

/printvars foo send 

...we got: Value=1, Time=22. 7444. 

Finally, as an extreme example of polymorphism, we set ‘Value’ to be a pro- 
cedure returning the current time in seconds, changing over time. 

(currenttime 60 mul round} /changevalue foo send 
/printvars foo send 1000 {pause} repeat /printvars foo send 
...we got: Vaiue=1449, Time=22.7444. 

...we got: Value=1450, Time=22.7444. 
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Window and Menu Packages 



This chapter presents two class-based packages, one for pop-up menus and the 
other for windows. In addition, we have provided a subclass of the standard win- 
dow implementation, ScrollingWindow. The general notion of a package is dis- 
cussed, and then the client interface specification for both packages is explained. 
A detailed sample program follows the explanation. A few hints on modifying 
the user interface conclude the chapter. 

To emphasize that these are “lightweight” implementations, these classes are 
called LiteMenu and LiteWindow. Their implementation files are 
litemenu.ps and litewin.ps For a more detailed explanation of the 
ScrollingWindow subclass see the section 7.2, A Scrollbar Implementation in 
$NEWSHOME/ lib/NeWS. 

7.1. Package Style To create a new instance of a class, use the /new method. To create a new 

instance of class ‘Foo’ and to assign it to the variable ‘foo,’ use: 

/foo argl ... argN /new Foo send def 

where argl ... argN are parameters used in initializing the new instance. The 
needed arguments vary from class to class. The /new method is the only method 
we describe that is sent to a class, rather than to an instance of a class. 

Many classes have several subclasses that can be used in place of the class itself. 
Thus one might have three subclasses of class ‘Foo’ that can be used anywhere 
‘Foo’ can. For example, suppose we have three interface styles: ‘SunViewFoo,’ 
‘MacFoo,’ and ‘NewsFoo.’ To allow the user to specify a preference, we use a 
variable, ‘DefaultFoo,’ that has assigned to it the current preference: 

/DefaultFoo SunViewFoo store 

Note the use of store rather than def; ‘DefaultFoo’ already exists and you want 
to change its value, not possibly create a new one in the current dictionary. The 
initial values for DefaultMenu and Default Window are LitePullRightMenu 
and LiteWindow, respectively. There are demo root menu entries that let you 
flip the default window and menu styles between a SunView-%ty\t and a NeWS- 
style set. This is done by simply changing the DefaultMenu and DefaultWin- 
dow definitions. 
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7.2. A Scrollbar 
Implementation 



Forking A Process 



Description Format 



/samplemethod 



7.3. Menu Methods 



ScrollingWindow is a subclass of LiteWindow. It is defined in 
$NEWSHOME/lib/litewin . ps. There are two simple scrollbars Tn tt 
frame margin. Two classes, Scrollbarltem and SimpleScrollbar, provide 
basis for this implementation. The former is an abstract superclass which 
the structure of scrollbars, but does not entirely implement one. Sim- 
pleScrollbar implements a simple, one button scrollbar. The two scrollbt 
initialized to return values between 0 and 1. When viewing a typical docu 
this corresponds to a position within the document, where 0 indicates the 1 
ning of the document, 1 is the end, and a fraction is somewhere in betweei 

A theme often encountered in the design and use of News packages is fork 
processes to perform tasks, especially if they may have considerable durat 
the menu package, for example, a process is forked to track the user intera 
with the menu, allowing other processing to occur in parallel. Similarly, t 
dow package will fork a process to redraw the client canvas so that other f 
ing can occur and so that the drawing itself may easily be intermpted. In t 
fish demo program, for example, you may perform other tasks while the 
being drawn, or you may interrupt the drawing of the fish to change the si; 
the window or to redraw the fish with different parameters. 

The interface descriptions below differ somewhat from the usual interface 
descriptions; only the arguments to the method are given, rather than the e 
description of the send. Thus, if the send for method ‘samplemethod’ Ic 
like: 

argl ... argN /samplemethod Foo send 
the interface description will look like: 

arg1 ... argN /samplemethod results 

with no mention of the object ‘Foo’ or the operator send. 

Menus associate a key, generally a string, with an action to be performed ■ 
that key is selected by the user. If the menu action is another menu, nestei 
displaying of that menu is performed. The default user interface style use: 
5urtWew-like pull-right nesting. 

Notice that the action procedure is more like the SunView notifier than a n 
traditional menu invocation that puts up the menu and waits for a returned 
This is quite intentional. NeWS favors greater use of multiple lightweight 
processes. While the menu is being tracked, other computing may also be 
formed. In particular, NeWS menus do not freeze or lock the screen. This 
sidered bad manners unless there is good reason for such locking behavior 
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Polymorphic Menu Keys 



/new 



Menu keys may be strings, icon names, procedures, or class instances. The string 
and icon name simply display the corresponding object. In addition, the menu 
keys may be wrapped in an array. This allows for font and color changes, and 
slight adjustments in the x,y location of the key relative to its default position. It 
also allows passing additional arguments to the user’s procedure or class 
instance. Thus 

[/Mylcon 1 0 0 rgbcolor .5 .5] 

is a key that shows ‘Mylcon’ in red with a slight (.5 .5) offset. 

The colomames demo has examples of advanced menu key usage. 

The following methods are used with menus, 

array -or- array array /new menu 

Creates a new menu. Sent to a menu class, generally DefaultMenu, to create an 
instance of the class. Typically, you use a single argument, which is assumed to 
be an array of key/action pairs. Thus: 

/MyMenu [ 

(Key1) {menuprod} 

(Key 2) {menuproc2} 

(Other =>) MyOtherMenu 

] /new DefaultMenu send def 

creates ‘MyMenu,’ which displays the strings 

(Key 1), (Key 2). (Other =>),... 

and associates the actions 

{menuprod}, {menuproc2}, MyOtherMenu, ... 

with these keys. If the action is a procedure, it is executed when the user chooses 
the associated key. If the action is another menu, it is treated as a pull-right 
menu, and nesting will occur. 

If a double argument is used, it is assumed to be an array of keys and an array of 
associated actions, respectively. If the second array is smaller than the first, it is 
‘padded’ with the last entry. This is mainly used when a single action will 
suffice for several keys. Thus: 

/PointSizeMenu 

[(10) (12) (14) (18) (24)1 
[ {SetPointSizeFromMenu} ] 

/new DefaultMenu send def 

might be used as a pull-right menu for setting the point size of a font. The pro- 
cedure will need to make use of the current menu selection using either /current- 
key or /currentindex below. For example: 

/SetPointSizeFromMenu { /PointSize currentkey cvi def } def 

sets the point size to be the integer value of the selected key. Note that we did 
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/popup 



/popup is a direct replacement for 
the original implementation of 
/show. It does a /showat using the 
current cursor location. 



/showat 



/currentkey 



/currentindex 



/searchkey 



/searchaction 



/insertitem 



not need to use /currentkey self send in this situation. The action prt^ 
called within the scope of the menu instance, and thus does not need tO ic- 
establish the menu’s context. 

- /popup - 

Pop-up the menu and track user actions; call the associated action if a key . 
selected. This is generally called from an event manager such as; 

/eventmgr [ 

MenuButton {/popup MyMenu send} 

DownTransition MyCanvas eventmgrinterest 
] forkeventmgrdef 

See Chapter 4, Extensibility through POSTSCRIPT Language Files, for desc 
tions of eventmgrinterest and forkeventmgr. 

xy or event /showat - 

Pop-up the menu and track user actions. A polymorphic method which can 
take a pair of integer values for location (x y) or an event whose location is 

- /currentkey key 

Returns the selected key when called within a menu action procedure. 

- /currentindex index 

Returns the index of the selected key when called within a menu action prc 
cedure. The indices begin at zero. 

key /searchkey index bool 

Searches for the given key’s position in the menu and returns the index of 
if found (along with a boolean of true) or simply the boolean false if the ke 
not found. 

action /searchaction index bool 

Searches for the given action’s position in the menu, returning a boolean o 
and its location if found, false otherwise. 

index key action /insertitem - 

Insert a new key/action pair into an existing menu at the given index. Thu 

0 (Do My Thing) {DoMyThing} /insertitem MyMenu send 

would add a new menu entry to the top of ‘MyMenu.’ If Index exceeds thf 
of the menu, the item is inserted at the end of the menu. 
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/deleteitem 



/changeitem 



7.4. Window Methods 



/new 



index /deleteitem - 

Remove the index-th menu item in the menu. Thus: 

0 /deleteitem MyMenu send 

would remove the topmost menu entry in ‘ MyMenu.’ If index exceeds the size 
of the menu, die last menu item is deleted. 

index key action /changeitem - 

Replace the menu item at the given index with a new key/action pair. Thus: 

0 (Do My Thing) {DoMyThing} /changeitem MyMenu send 

would replace the menu entry at the top of ‘MyMenu.’ If index exceeds the size 
of the menu, the last menu item is changed. 

A window in NeWS is simply a set of canvases and an event manager. The default 
window style manages a FrameCanvas, a ClientCanvas, and an IconCanvas. 

It provides two types of user interface management: menu interaction and direct 
mouse interaction with the window or icon. See the section on default user inter- 
face below for details. 

In the following descriptions of window methods, window/ icon means the win- 
dow or its icon, depending on whether the window is open or closed. If the win- 
dow is open, the method refers to the window frame. If the window is closed, the 
method refers to the window icon. 

Also, many of the window methods generally are not used by the client directly, 
but are accessed primarily through the user interface to the window. These 
methods are identified below with (UI). 

canvas /new window 

Creates a new window. Sent to a window class, generally Default Window, to 
create an instance of the class. The canvas is the parent canvas for the window 
and is generally framebuffer. After creating a window, a client will want to 
modify the window by changing its drawing routines, adding a client menu, 
changing its frame or icon label, etc. The client makes these modifications by 
changing instance variables in the new window (typically, by sending the win- 
dow an executable array as a method). 

First, the standard creation of a window: 

/win framebuffer /new DefaultWindow send def 

Then, the modification of the window: 
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{ 

/FrameLabel (Hello World) def 
/PaintClient {MyPaintProc} def 
/IconLabel /hello_world def 
/ClientMenu [ 

(First Menu Label) {MyFirstMenuAction} 

(Next Menu Label) {MyNextMenuAction} 

] /new DefaultMenu send def 
} win send 

Table 1-1 contains the instance variables that are commonly modified, along 
their initial values; there are other instance variables available, but the interf 
to them is prone to change. 



Table 7-1 Lite Window Instance Variables 



Instance Variable 


Initial Value 


FrameLabel 


nullstring 


IconLabel 


nullstring 


Iconimage 


null 


PaintClient 


nullproc 


ClientMenu 


null 



/destroy - /destroy - 

Destroy the window and its entire process group. (UI) 

/reshape x y width height /reshape - 

Note: This does not force the shape Reshape the window to have the given bounding box. 
to be rectangular, just to fit within 
the bounding rectangle. 

/reshapefromuser - /reshapefromuser - 

Reshape the window to have a new bounding box. The user is prompted for 
bounding box, and the results are passed to /reshape, /reshapefromuser is 
tially called by the client, but is then handled by the window’s user interface 
(UI) 

/map - /map - 

Make the window/icon visible. Fork the window’s event manager if that has 
already been done, /map is initially called by the client, but is then handled 
the window’s user interface. (UI) 
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- /unmap - 

Make the window/icon invisible. (UI) 

- /flipiconic - 

Alternate between opened (window) and closed (iconic) state. (UI) 

X y /move - 

Move the window so that its bottom left comer (its origin) is at the coordinates x 
y in its parent canvas. (UI) 

- /paint - 

Repaint the window or icon. If the window is open, paint calls both 
/paintframe and /paintclient. The default /Damaged handler sets the canvas 
clip to the damage region and calls /paint automatically. (UI) 

- /paintclient - 

Repaint the window’s client canvas. The default action is to call the instance 
procedure variable PaintClient. It uses the value of ForkPaintClient? to con- 
trol whether it will fork a process to do the repaint (the default). You should 
make sure your PaintCIient uses pause where appropriate, so that other 
processes can run while you are painting. 

/paintframe - /paintframe - 

Repaint the window’s frame. This includes the frame label and controls. The 
instance variable FrameLabel holds the label string. Changing this and invok- 
ing paintframe will change the frame’s label. 

/painticon - /painticon - 

Repaint the window’s icon. The default action is to set the canvas to IconCan- 
vas and call Painticon. This in turn defaults to using Iconimage and IconLabel 
to paint the icon. Clients typically either replace the Painticon procedure with 
one that does all its own drawing, or set either Iconimage or IconLabel and use 
the default Painticon procedure. Iconimage is initialized to null. Setting it to 
the name of an icon in the system icon font, such as /helio_world, will cause that 
icon to be drawn. IconLabel is initialized to the empty string. 



/unmap 



/flipiconic 



/move 



/paint 



/paintclient 
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/totop 



/tobottom 

7.5. An example: 



- /totop - 

Puts the window/icon above all canvases. (UI) 

- /tobottom - 

Puts the window/icon under all canvases. (UI) 

1 ines The following is an in-depth look at a sample demo program, lines, whic 
creates a window and associates a menu with its client canvas. The progran 
draws lots of lines (in color, if you are using a color machine). The menu cc 
trols the number of lines drawn. Here’s the complete program; 
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#! /usr/NeWS/bin/psh 
% 

% lines 6.3 87102124 
% 

% Draw a window with a bunch of lines. 

% The icon uses the same drawing procedure as the client. 
% 

/fillcanvaswithlines { 
gsave 
1 fillcanvas 
0 setgray 

clippath pathbbox scale pop pop 
0 13-1 roll div 1 { 

ColorDisplay? {dup 1 1 sethsbcolor} if 
0 0 moveto 1 1 index lineto stroke 
0 0 moveto 1 lineto stroke 
pause 
} for 

grestore 

} def 
/main { 

/linesperside 10 def 
/setlinesfrommenu { 

/linesperside currentkey cvi store 
/paintclient win send 

} def 



% linesperside => — 

% Paint the background 
% Set the default color black 
% Set scaling to beO to 1 
% 0 delta 1 {..} for 
% Set color if ColorDisplay 
% Draw line to top 
% Draw line to side 
% Let others run 



% Start with 1 0 lines per side 
% - => - (Set linesperside from menu) 
% Set linesperside 
% Ask window to draw me 



/win framebuffer /new DefaultWindow send def % Create a window 

{ % Install my stuff 

/FrameLabel (Lines) def 

/Paintclient {linesperside fillcanvaswithlines} def 
/Painticon {10 fillcanvaswithlines 0 strokecanvas} def 
/ClientMenu 



[ (2) (4) (8) (10) (20) (100) (250) (500) (1000) ] 

[ {setlinesfrommenu} ] /new DefaultMenu send def 



} win send 

/reshapefromuserwin send % Shape it 



/map win send 



}def 

main 



% Map the window 

% (Damage causes PaintClient to be called) 



The program is written as a psh script that sends the rest of the file to the News 
server. The program consists of two procedures, ‘fillcanvaswithlines’ and 
‘main,’ and a call to ‘main.’ 

The ‘fillcanvaswithlines’ procedure takes as an argument the number of lines 
per side to draw. Andmportant point to notice here is the use of pause in the for 
loop. This allows the lightweight process mechanism to optimize interactive 
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behavior. Be sure to use pause in any part of your program that will pc^^j: 
take a long time. In this case, if the user has selected 1000 lines, the dr^v^ifig 
could last several seconds. However, there is a cost in using pause; a more 
efficient version of the lines example would pause every 10-20 sets of ve 
tors. 

The procedure ‘main’ initializes the ‘linesperside’ parameter, defines a mei 
action procedure, ‘setlinesfrommenu’, and initializes the program’s windo' 

‘setlinesfrommenu’ sets the ‘linesperside’ parameter by converting the mt 
key string into an integer. Note the use of store; this is necessary because w 
changing a predefined value in userdict in a context potentially having sevei 
other dictionaries on the dictionary stack. We could have used 

userdict /linesperside currentkey cvi put 

instead. Finally, ‘setlinesfrommenu’ causes the client canvas to be repainti 
sending /paintclient to ‘win.’ We do this rather than simply calling ‘fillcanv 
withlines’ directly in order to inherit window manager side effects (mainly t 
use of forking the client paint procedure). 

The window initialization consists of creating a default window, installing o 
modifications, setting its shape from user input, and finally making it visible 
The modifications we install set the frame label to the string (“Lines”), set t 
client repaint procedure to call ‘fillcanvaswithlines’ with the current value c 
‘linesperside’, set the icon to draw itself using ‘fillcanvaswithlines,’ and fi 
set the client canvas’ menu to be one that resets the ‘linesperside’ pargg’^te 
Note that we map the window as our last step. This is intentional — rrs^j^^ir 
should be deferred until all setup is performed. 

7.6. Default User Interface The (current) default window frame and icon surface use all three mouse bu 

The buttons are identified according to the following definitions in init . j 

Table 7-2 Window User Interface Button Usage 



Button Name 


Initial Value 


PointButton 


LeftMouse Button 


AdjustButton 


MiddleMouseButton 


MenuButton 


RightMouseButton 



You may want to redefine these according to taste. 



PointButton PointButton operates as follows: 

o In the frame “go-away” region (top left): causes the window to close. 

□ In the frame “stretch” region (bottom right): lets the user stretch the wi 
dow by that comer. 

□ Elsewhere in the frame: brings the window to the top of the window pilt 

□ Anywhere in the icon: opens the window. 
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AdjustButton AdjustButton operates as follows; 

□ Anywhere in the frame or icon: moves the window or icon. 

MenuButton MenuButton operates as follows: 

□ Anywhere in the frame or icon; pops up the window or icon menu. 

Modifying the User Interface To change the default settings for the packages, simply put lines like these in 

your user .ps file: 

% Swap the Adjust and Menu mouse buttons. 

/PointButton LeftMouseButton def 
/AdjustButton RightMouseButton def 
/MenuButton MiddleMouseButton def 

% Change the font in menus, and box the selected menu item instead of filling it. 
DefaultMenu begin 

/Menu Font /Times-italic findfont 12 scalefont def 
/StrokeSelection? true def 
end 

% Change the font for frame headers. 

DefaultWindow begin 

/FrameFont /Times-Roman findfont 1 2 scalefont def 
end 

The following code will allow you to swap the mouse buttons for selections in 
psterm as well: 

UserProfile begin 

/Viewpoint PointButton def 

/ViewFocus PointButton def 

/ViewAdjust AdjustButton def 

/ViewRestore AdjustButton def 

end 
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8.1. Introduction 



Contacting the Server 



Debugging 



A primitive NeWS debugging package is available. It allows you to set break- 
points and print to debugging output windows. It also has a simple facility for 
automatically causing breaks when errors are encountered. This should be con- 
sidered simply a tentative poke at the problem. Because the debugger is written 
in the POSTSCRIPT language, users may modify it for their own purposes. 

The News debugger is simply the POSTSCRIPT language itself with a few added 
commands in the file debug.ps. This file is not loaded during the standard 
initialization process; you need to execute the following code to load the debug- 
ging commands: 

(NeWS/debug.ps) run 

Normally you would do this by including this line in your user . ps file; see 
Modifying the N^S Server in Appendix A, Using N^S, for more information on 
the user. ps file. 

The usual style of debugging is to create one or more interactive connections to 
the News server and start a debugger on each. You can contact the server from 
any shell using the psh(l) command; see Talking Directly to the Server in 
Appendix A, Using A'eWS, for more information about contacting the server. 

After the connection is made, a PostScript language executive must be invoked 
by typing the executive command. To make this a debugging connection, you 
then run the command dbgstart. 

NOTE Typing dbgstiart will make the server try to start an executive for you if one 
is not running already; However, there are situations where this can fail. If 
problems occur, start the executive before typing dbgstart. 
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Starting a Debugging Session 



8,2. The Debugging 
Environment 



Multi-Process Debugging 



8.3. Client Commands 



A typical initial sequence will look like: 

paper% psh 

executive 

Welcome to NeWS Version 1.1 

dbgstart 

Debugger installed. 

This assumes (NeWS /debug .ps) run has already been executed from 
user . ps file. Had this not been done, you would have had to type 

(NeWS/debug.ps) run before typing dbgstart. 

Debugging commands fall into two categories: commands executed from cl 
programs (client commands) and commands executed as a debugging user ( 
commands). The user commands are those executed from the psh connec 
to the server, while the client commands are those put in the code being 
debugged. 

dbgstart forks a debugger process that is attached to the psh connection a 
“listens” for debugger-related events generated by client commands. (Act 
all client commands simply broadcast debugger events to these debugger di 
mons!) Any client command that causes printing will print in each debuggi 
psh connection. 

NeWS is a multi-process environment so there is the problem of debug^^ 
several processes at one time. The solution the debugger implements is to 1 
each debugging connection maintain a list of processes that are paused for 
debugging. This list is printed via the dbglistbreaks command below. It i: 
printed whenever a new break occurs. Any of the listed breaks can be entet 
using the dbgenterbreak command. This swaps the psh debugging conn 
out and replaces it with the paused process. The context currently consists ' 
diet stack and operand stack. 

These are the client commands: 



dbgbreak name dbgbreak - 

Causes the current client to pause, printing the pending breaks in all debugs 
connections. Name is used as a label in the list to distinguish between breal 
e.g. /Break) . 

See also: dbgbreakenter, dbgbreakexit 
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dbgprintf 



<errors> 



8.4, User Commands 



formatstring argarray dbgprintf - 

Prints on each debugger connection, in printf style. If there are no debugger 
connections, it prints on the console. Thus: 

(Testing: % % %\n) [1 2 3] dbgprintf 

will print: 

Testing: 123 

on each debugger connection. 

See also: printf, dbgprintfenter , dbgprintfexit 

In addition to the above explicit calls to the debugger, errors cause the debugger 
to be implicitly invoked. This is done by the debugger putting a special error 
dictionary in the system dictionary. Each error slot in this debugger-supplied 
dictionary has a call to the debugger for each error. See the PostScript Language 
Reference Manual for details on error handling. 

- <errors> - 

While debugging, a client error causes the client program to break to the 
debugger. This is exactly the same as inserting the code 7<errorname> 
dbgbreak’ at the point the error occurred. Here is the result of encountering an 
undefined error while a debugger is running: 

Break : /undefined from process (4154624^ breakpoint) 

Currently pending breakpoints are: 

1: /undefined called from process ( 4154624^ breakpoint) 

Most of the user-level debugger commands come in two forms: one that expli- 
citly takes a breaknumber and one that does not. The general rule is: 

n A command of the form cmdwamebreak expects an explicit breaknumber for 
its argument. 

□ A command of the form cmdname (without ‘ ‘-break”) uses an implicit 
breaknumber. This number is generally the currently entered break, or the 
last break in the list if there is no currently entered break. 

The implicit form is primarily used in the most common case of only one break 
pending, or where constantly restating the breaknumber for the currently entered 
process would be arduous. 
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dbgstart 



dbgstop 



dbglistbreaks 



dbgbreakenter 



dbgbreakexit 



dbgprintfenter 



These are the user commands; 

- dbgstart - 

Make the current connection to the server a debugger. Required before any 
the other commands below can be used. 

- dbgstop - 

Removes the debugger from your psh connection. 

- dbglistbreaks - 

List all the pending breakpoints resulting from dbgbreak above. They are 
in the following form: 

dbglistbreaks 

Currently pending breakpoints are: 

1: /oneA called from process (4245774, breakpoint) 

2: /oneB called from process (4306134, breakpoint) 

3: /menubreak called from process (5177764, breakpoi 
4: /undefined called from process (4154624, breakpoi 

The number preceding the colon is the breaknumber used in many of the fo 
ing commands. A number beyond the end of the listing behaves as the last 

name/[dict name] dbgbreakenter - 

Modify the named procedure to call dbgbreak just after starting. If name i; 
array, it is assumed to be a diet and the name of a procedure in the diet. Th 
break when any new window is made: 

[DefaultWindow /new] dbgbreakenter 

Break: /new from process (4050350, input_wait) 

Currently pending breakpoints are: 

1: /new called from process (4050350, input_wait) 

See also: dbgbreak 

name/[dict name] dbgbreakexit - 

Modify the named procedure to call dbgbreak just before exiting. 

See also: dbgbreak 

name/[dict name] formatstring argarray dbgprintfenter - 
Modify the named procedure to call dbgprintf with formatstring and argar 
just after starting. Note that argarray can be a literal array if you want to de 
evaluation of the arguments until the dbgprintf occurs. 

See also: dbgprintf 
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clbgprintfexit name/[dict name] formatstring argarray dbgprintfexit - 

Modify the named procedure to call dbgprintf With formatstring and argarray 
just before exiting. 

Note that argarray can be a literal array if you want to defer evaluation of the 
arguments until the dbgprintf occurs. 

[Def aultWindow /reshape] (resize: % % % %\n) 

{FrameX FrameY FrameWidth FrameHeight } dbgprintfexit 

resize: 91 100 179 181 
resize: 91 94 223 187 

See also: dbgprintf 

dbgwherebreak breaknumber dbgwherebreak - 

Prints a exec stack trace for the process identified by breaknumber: 

1 dbgwherebreak 

Level 1 

{ /too 10 'def' /bar 20 'def' /A 'false' 'def' /B 'true' 

'def' /msg (Hi!) 'def' (Testing: %\n) 'mark' msg ] dbgprintf 
/oneB *dbgbreak } (*21,22) 

Level 0 

{ 100 'diet' 'begin' array{22} *'loop' 'end' } (*4,6) 

The asterisk indicates the currently executing primitive in each level. The two 
numbers following each procedure are the index, relative to zero, of the asterisk 
and the size of the procedure. This is useful information for using dbgpatch. 

dbgwhere - dbg where - 

Prints the execution stack for the currently entered process or for the last process 
listed if no process is currently entered. 

dbgcontinuebreak breaknumber dbgcontinuebreak - 

Continues the process identified by breaknumber. 

- dbgcontinue - 

Continues the currently entered process or the last process listed if no process is 
currently entered. 

breaknumber dbgenterbreak - 

As far as possible, make this debug connection have the same execution environ- 
ment as the process identified by breaknumber. Currently, this includes the 
operand stack and the dictionary stack. Thus dbgenterbreak allows you to 
browse around in the given process’ state. If dbglistbreaks is executed while 
within an entered process, the listing will indicate that process with a “=>” in 
the left margin: 



dbgcontinue 



dbgenterbreak 



The effects of this change will per- 
sist until the News server is res- 
tarted. 
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dbgenter 



dbgexit 



dbgcopystack 



dbgcallbreak 



dbgcall 



dbggetbreak 



dbgpatchbreak 



3 dbgenterbreak 

dbglistbreaks 

Currently pending breakpoints are: 

1: /oneA called from process (4245774, breakpoint) 

2: /oneB called from process (4306134, breakpoint) 
=>3 : /menubreak called from process (5177764, breakpoi 



- dbgenter - 

Enters the last process listed. 

- dbgexit - 

Return to the debugger connection from whatever process you may have en 
This is a no-op if no process is currently entered. The following debugger j 
tives will call this routine: dbgcontinuebreak, dbgkillbreak, dbgenterbre 
dbgstop. Thus, dbgenterbreak first calls dbgexit to insure preserving stat 

- dbgcopystack - 

Copies the current operand stack to the process being debugged. This allov 
to dbgenter a process, modify that copy of the operand stack, and copy it b 
the process. 

arg clientproc breaknumber dbgcallbreak - 
Execute clientproc in the broken process with arg as data. The clientproc 
itive will be executed (in the client environment) with the arg on the stack, 
is responsible for popping it off. 

arg clientproc dbgcall - 

Implicit version of dbgcallbreak. 

breaknumber dbggetbreak process 

Returns the NeWS process object for the given breaknumber. 

level index patch breaknumber dbgpatchbreak - 
Patch the execution stack for breaknumber process. The patch overwrites t 
word in the executable at the given level, and at the given index within that 
Prints the resulting execution stack (dbgwhere). 
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dbgpatch 

dbgmodifyproc 

dbgkilibreak 

dbgkill 

8.5. Miscellaneous Hints 

Aliases 



Use Multiple Debugging 
Connections 



level index patch dbgpatch - 
Patch the implicit process. 

name/[dict name] headproc tailproc dbgmodifyproc - 
Modify the named procedure to execute headproc just before calling it, and to 
call tailproc ju^t after calling it. In affect, ‘{proc}’ becomes ‘{headproc proc 
tailproc}.’ This is the mechanism used for implementing dbgbreakenter/exit 
and dbgprintfenter/exit. 



breaknumber dbgkilibreak - 

Kills a breakpointed process, removing it from the breaknumber list. 

- dbgkill - 

Kills the default process. 

Here are some miscellaneous tips for debugging. 



Because the debugger is POSTSCRIPT language-based, the above commands can 
easily be modified or overridden entirely. One common change is to define some 
easily-typed aliases for the above verbose names. The following POSTSCRIPT 
language code does the trick; you can add this to your user .ps file to make 
the aliases available in all debugging connections. 

/dbe {dbgbreakenter} del 

/dbx {dbgbreakexit} del 

/dc {dbgcontinue} del 

/deb {dbgcontinuebreak} del 

/dec (dbgcopystack dbgcontinue} del 

/dcs {dbgcopystack} del 

/de jdbgenter} def 

/deb {dbgenterbreak} def 

/dgb {dbggetbreak} def 

/dk {dbgkill} def 

/dkb {dbgkilibreak} def 

/dib jdbglistbreaks} def 

/dmp {dbgmodifyproc} def 

/dp {dbgpatch} def 

/dpe jdbgprintfenter} def 

/dpx jdbgprintfexit} def 

/dw {dbgwhere} def 

/dwb {dbgwherebreak} def 

/dx jdbgexit} def 



If you are debugging POSTSCRIPT language code that you are running directly 
from an executive, start a debugging executive in another psh connection. This 
avoids having the debugging code trying to break to itself. You use the first exe- 
cutive to run the code being tested, and the second one to trap the errors. 
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C Client Interface 



The C to PostScript language (CPS) interface has been designed to facilitate 
interactions between programs written in the C language on the “client” side and 
the News server on the “POSTSCRIPT language” side^. The interface model is of a 
client program which constructs a NeWS program and then, after opening a con- 
nection to the server, transmits the program. This program may make use of the 
all the built-in features of News (including procedures already defined in the 
userdict and the systemdict). 

With this code now resident in the News server, the client side program can make 
calls to the server side — initiating remote execution. The CPS interface defines; 

□ the format of the .cpsfile 

□ the functions which establish and close communication with the News server 

□ a format for passing information between client and server 



9.1. How to Use CPS There are three component files used in the construction of a News client. These 

are: 

□ the . cps file - containing the POSTSCRIPT language code to be executed 
within the server, 

□ the . h file - containing the POSTSCRIPT language code in a form recogniz- 
able to the C compiler, 

□ the . c file - the client program, which can use POSTSCRIPT programs. 

The CPS program acts to convert the contents of the . cps file into a form useable 
by a C program. The POSTSCRIPT language functions (after conversion) can now 
be called from the C program and execution will take place within the server (on 
the PostScript language side). An explanation of their use may be found in the 
following section ( T/ie .cps File). 

The CPS program needs only one argument (though it has a number of options), 
the name of the file to translate: 



® News is not limited to communication with programs written in C. Other interfaces may be designed 
relatively easily. 
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X % cps test.cps 



The input file in the above example is translated by CPS into a header file (a 
file)^. This header file is then #include’d in the client (C) program before 
compilation. It will contain not only the definitions that you have made but a 
number of additional functions that CPS provides (see the section 9.5 on The < 
Utilities . 

It is best to transmit information to the server once and place procedures and 
variables to be used more than once in a local dictionary. An error will be ge: 
erated on the POSTSCRIPT language side if you attempt to reference a procedi 
or variable (other than implementation-associated ones) that you haven’t plac 
in a dictionary. 

There is no need to include the standard i/o header file (stdio.h) because CPS 
this already. However, you will need to add the CPS library to your list of 
libraries searched by the linker. Further, you will need to add the file psio . 
the compile line (or as a #include ) in your file. This may be done at com 
time with the following command line form: 

^ ^ ^ 

X % cc -I$NEWSHOME/include test.c /usr/NeWS/lib/libCF 

V ^ ■ ■ '■ ■ 



where the pathname provided to the compiler is the full pathname of the£2S 
library (if it is not in your current directory). 

The . cps File The . cps file provides the input for the CPS program. The CPS program buih 

header file of the proper form for inclusion in a client program written in the 
language. 

The . cps file contains definitions of the following form: 
cdef macro__name ( ) procedure 

V 

where the macro name is the name of the macro as you wish to label it withi 
your client side program, procedure is the POSTSCRIPT language procedure ti 
you wish to invoke. For example, the p s_mo vet o () procedure is specific 
this way: 

f 

cdef ps_moveto (x, y) x y moveto 

V ^ 

CPS understands how to construct very efficient C code fragments that packar 
and transmit POSTSCRIPir language fragments. The arguments to the C proce 
are inserted where they are referenced in the POSTSCRIPT language fragment. 
The invocation: 



^ The input file is passed through cpp ( 1 ) before it is read by cps. 
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causes this POSTSCRIPT language fragment to be transmitted: 




To reduce communication costs, it is best to keep POSTSCRIPT language frag- 
ments that will be used often as short as possible. One good way of doing this is 
by defining POSTSCRIPT language procedures: 




Invoking initialize () will transmit the definition of the POSTSCRIPT 
language function draw-dot a single time. Further invocations of the routine 
dr aw_dot (with a call to draw_dot ( x , y ) ) will require the transmission of 
fewer bytes. 

Argument Types Just as in normal C procedure declarations, the parameters to CPS macros must be 



given types. The syntax for specifying a type is different: the type name appears 
preceding the parameter in the parameter list®. For example, the previous 
definition of ps moveto ( ) is equivalent to: 




Most of the types correspond directly to C types. The following table lists the 
CPS argument types: 



Table 9-1 CPS Argument Types 



CPS type 


C type 


int 


int 


float 


float or double 


String 


char * 


cstring 


char * with an accompanying count of the number of 
characters in the string. Such a parameter is actually two 
parameters: the pointer to the string and the count. 


fixed 


A fixed-point number represented as an integer with 16 
bits after the binary point. See the description of 
integer in Table 13-2, Implementation Limits of the 
PostScript Language Reference Manual. 



The default type of these arguments is int (as in the C language). 
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Table 9- 1 CPS Argument Types — Continued 



CPS type 


C type 


token 


A special user-defined token. This is described in the 
section on user tokens. 



The header (.h) file is created by the CPS utility. It should be included in you 
client C program using the #include feature of the C pre-processer. In additi 
the routines that have been defined in the . cps file, this file includes a num 
of pre-defined POSTSCRIPT language routines (listed in the final section of tl 
chapter, The CPS Utilities). 

The client side C program is written in much the same fashion as you would 
write any C program. The functions that have been declared on the server sii 
(with cdefs) are accessible to you on the client side. While the CPS interface 
definition does the low-level work of passing these values in a form that you 
program can understand, you will still have to explicitly open and close cotr 
munciation with the NeWS server. 

Communication with the Server Communication with the server is handled by three CPS functions. These fui 

tions manage the low-level work of determining which server to connect to, 
establishing the connection, requesting execution of POSTSCRIPT language c 
and severing the connection to the server cleanly. These functions are part o 
body of functions that define the CPS interface and which are made avai»^% 
the inclusion of the CPS library during compilation. 

Opening a Connection A connection to the News server is establishing by calling the CPS function 

ps_open_PostScript ( ) . This function returns a PSFILE pointer if a ■ 
nection to the NeWS server is successfully established, otherwise a 0 . The f 
tion determines which server to connect to by examining the environment v: 
able NEWSSERVER^. 

ps_open_PostScript ( ) must be called before any other procedure tha 
needs to communicate v^^ith the server. 

Connection Files Two PSFILE pointers, PostScript and PostScriptInput , are the 

duits through which information flows between News server and client progr 
When the client writes to the NeWS server, it is writing on the file representec 
the pointer, PostScript. When it (the client) reads output from the serve 
is reading the file PostScriptInput. All operations on these PSFILE 
pointers are done using the psio package, not the standard I/O. See the psu 
manual page for an explanation. Examples of this may be found in Chapter 
Complete Example: roundclock. 



The . h File 



The . c File 



For a detailed explanation see Chapter 15, Supporting News from Other Languages. 
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Buffered Output to the Server 



Closing a Connection 



Comments 

9.2. Tags, Tagprint, 
Typedprint 



Tags 



Output to the News server is buffered in order to provide a more efficient inter- 
face mechanism. The contents of the buffer will be sent to the server when the 
CPS function ps_f lush_PostScript ( ) iscalled. 

The connection to the server is terminated when the CPS function 
ps_close_PostScript ( ) is called. This function should be called before 
the client program exits. When invoked it causes all NeWS processes running 
within the server on the client’s behalf to be terminated. 

The CPS comment convention is the same as the POSTSCRIPT language comment 
convention: everything from a % sign to the end of a line is a comment. 

There are many ways to implement a communication protocol between client and 
server. In the CPS interface we have chosen to use a tagged packet method. The 
server side communicates with the client program by packaging information into 
packets. These packets are tagged with an identifying number and the informa- 
tion passed in them is typed. 

The section The . cps File explains how to call a POSTSCRIPT language func- 
tion from the client side. This tagged packet method may be said to be the com- 
plementary half of that system. 

The CPS interface procedures for receiving input from the News server are some- 
what more complicated than the procedures presented in the preceding sections 
that send POSTSCRIPT language fragments to News. The body of a specification 
has three parts: 

1 . A label (name) with args that the client side program can use. 

2. An identifier (tag). 

3. The PostScript language routine or code fragment to be associated with 
the label. 

4. A list of variables to receive the values in the reply (results). 

The syntax of a specification is; 

cdef name {args) PostScript language code => tag (results) 

These three parts correspond to three phases in the client execution of a CPS pro- 
cedure: 

1. Transmission of the PostScript language code. 

2. Waiting for the return of the tagged reply. 

3. Setting any result values from the reply. 

The rag field is optional (as are the args and results) fields. Thus, a specification 
may be brief as well as lengthy. Both of the following specifications are accept- 
able; 
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Figure 9- 1 Short Tags Specification 




which will execute the PostScript language routine makewin within the 
server when the execute ( ) function is called from the C client, and 



FigurG 9-2 Long Tags Specification 



#define BBOX_TAG 57 

cdef ps_bbox(x0,y0,x1 ,y1 ) => BBOX_TAG (y1 , x1 , yO, xO) 
clippath pathbbox % Find the bounding box of 
% the current clip. 

BBOX_TAGtagprint % Output the tag. 
typedprint % Y1 is on the top of the stack, 
typedprint % then x1 . This is why the return 
typedprint % list is in the opposite order from 
typedprint % the argument list. 

V 

The long specification defines a C function called ps_bbox that takes as 
parameters four pointers to integers. It sets the integers to the bounding_box 
the current clipping path. When ps_bbox ( ) is called it starts by tra^^it 
a block of PostScript language code to the News server. In this case, the ‘( 
path pathbbox’ call returns the bounding box of the current clipping regioi 
then transmits back the tag and results. 

Receiving Tagged Packets from The tag is necessary in the reply to deal with the possibility of multiple asyr 
News nous messages being sent from the server to the client. For example, if the 

PostScript language code that handles menu selections executes this code 
the user selects something from the menu: 

/ 

MENU_HIT_TAG tagprint 
menuindex typedprint 

V 

then tagged packets will be coming back from the server to the client at timt 
determined by the users interaction, possibly intermixed with replies to requ 
like ps_bbox. The tags let the client side libraries sort out which replies ; 
which requests. 

To generate a stub for receiving messages like the menu hits in the previous 
example, you can use cdef with a tag and return value list, but without an 
PostScript language code: 

— 
cdef ps_menu_hit (index) => MENU_HIT_TAG (index) 

< 

t ") 

In this case ps_menu hit ( ) will be a function, not a procedure. ItV.!! 
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to see if the first message on the received message queue is a menu hit. If it is, 
then it will unpack its arguments and return tme, removing the tag and arguments 
from the queue. Otherwise it will return false, leaving the queue alone. If there 
is nothing in the received message queue, then the function will wait until some* 
thing is received. 



Functions like ps_menu_hit ( ) are generally used to construct the basic com- 
mand interpretation loops of client programs by using a cascade of them in a pol- 
ling fashion: 




tagprint and typedprint The tagprint statement sends the tag ‘BBOX_TAG’ back to the client. It places 

the specified value on the input stream (the file Post Script Input) from 
which the client side retrieves it. The C client has been waiting for such a tag and 
the subsequent ‘typedprint’s return the coordinates to the client. The 
‘typedprint’ s can return any variables of the types listed in the above table, CPS 
Argument Types, 

9.3. A Sample Tags Following are two short sample programs. Together, they form a pair which will 

Program allow you to return a menu choice from the News server side to the C client side. 

Remember when you create them to label the CPS file as test.cps. The CPS pro- 
gram will create a test.h file that your C program can use. 

Figure 9-3 A Server Side Tags Program 
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/FillCanvasWithStar { % stargray fillgray => - 
fillcanvas setshade 
clippath pathbbox starpath fill 
} def 

/SetStarGrays { % stargray fillgray => - 

SET_GRAYS_TAG tagprint typedprint typedprint 
}def 



/win framebuffer /new DefaultWindow send def 

{ 

/FrameLabel (Tag Test) def 
/Painticon {.25 .75 FillCanvasWithStar} def 
/PaintClient (1 0 FillCanvasWithStar} def 
/ClientMenu [ 

(Black on White) { 0 1 SetStarGrays} 

(Black on Gray) { 0 .5 SetStarGrays} 

(Gray on White) { .5 1 SetStarGrays} 

(Gray on Black) { .5 0 SetStarGrays} 

(White on Black) { 1 0 SetStarGrays} 

(White on Gray) { 1 .5 SetStarGrays} 

] /new DefaultMenu send def 
} win send 

/reshapefromuserwin send 
/map win send 

cdef get_grays(float star, float fill) => SET_GRAYS_TAG (fill, star) 

cdef set_grays(float star, float fill) 
win /PaintClient (star fill FillCanvasWithStar} put 
/paintclient win send 



Figure 9-4 A Client Side Tags Program 

— 

r A very simple NeWS client */ 

#include "psio.h" 

#include "test.h" 

main() 

{ 

float stargray, fillgray; 

if (ps_open_PostScript() == 0 ) { 

fprintf(stderr,"Cannot connect to NeWS server\n"); 
exit(1); 

} 

initializeO; 

while (!psio_error(PostScriptlnput)) { 
if (get_grays(&stargray, &fillgray)) { 
set_grays(stargray, fillgray); 
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} else if (psio_eof(PostScriptlnput)) { 


S 


break; 

} else { 

fprintf ("Strange stuff !\n"); 
break; 

} 




} 

ps close PostScriptO: 

} 




V 





9.4. Tokens and 
Tokenization 



News provides a facility for establishing and maintaining a token list. The mes- 
sages that a client program sends to the NeWS server are sequences 



CAUTION Using the features described here is a performance optimization. You are 
encouraged not to bother with them until you have your application run- 
ning, and even then only if communication and interpretation overheads are 
a problem. 

The token list is a very efficient mechanism for the compression of data prior to 
transmission. The list is variable in length with a maximum dimension of 1056 
elements. The first thirty-two (32) elements are tightly compressed, yielding a 1- 
byte token. The latter 1024 tokens generate two-byte codes. 

Several operators are defined by the CPS utility to allow you to add and retrieve 
tokens from the token list. When a token is added to the list, it is available when- 
ever the token is found by the scanner in the input stream^®. 

News has a mechanism, supported by CPS, where a client program and the server 
can cooperatively agree on the definition of a user token. The CPS declaration: 

usertoken black 

tells CPS that you want to transmit the user-defined token black in compressed 
form. When black appears in following CPS definitions, the compressed token is 
used in the definition. 

In order to establish the meaning of the token, the client has to talk to News 
before the first use of the token. There are a number of procedures that the C 
program can call to do this: 

ps_def ine_stack_token(u) 

Takes the value on the top of the POSTSCRIPT language stack in the server 
and defines it as the value of the token u. In future messages to POSTSCRIPT 
language, u is this value. 

ps_def ine_value_token(«) 

Defines the user token u to be the same as the current value of the 
PostScript language variable u. In future messages to POSTSCRIPT 

It is frequently useful to add font objects to the token list and save the lookup time. 

#sun 
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language, u is the value that the POSTSCRIPT language variable u h/^^; 
time ps_def ine_value_token 0 was called. Future chang^m 
value of the POSTSCRIPT language variable u, or its identity as determii 
by changes in variable scope, have no effect on the definition of the tok 

ps_def ine_word_t.oken(M) 

Defines the user token u to be the name of the POSTSCRIPT language vt 
u. In future messages to POSTSCRIPT language, u the POSTSCRIPT lang 
variable u. This binds the token u to the name u. When it is sent to 
PostScript language, the name u is evaluated and its value is used. 

The operators that manipulate the token list are listed in the table in the foil 
section. 

9.5. The CPS Utilities The following utilities are provided for your use when a . h file is created 1 

cps utility. You may use these functions without defining them on the serv 
side. This list does not describe the arguments to these functions. You shoui 
look at the header file for the complete form of the function. 



Function 


Description 


psopenPostScript 


open connection to News server 


ps close PostScript 


close connection to News server 


psflushPostScript 


flush the output buffer 


ps_moveto 


moveto 


psrmoveto 


rmoveto 


pslineto 


lineto 


ps_rlineto 


rlineto 


psclosepath 


closepath 


ps_arc 


arc 


ps stroke 


stroke 


ps_fill 


fill 


ps_show 


show 


pscshow 


cshow 


ps_findfont 


findfont 


ps_scalefont 


scalefont 


pssetfont 


setfont 


ps_gsave 


gsave 


psgrestore 


grestore 


ps finddef 


takes font,scale returns index into token list 


ps_scaledef 


takes font and returns index into token list 


ps_usetfont 


takes ’font token’ and returns a font object 
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A Complete Example: roundclock 



Here is a complete example, the clock program. We start with the C program, 
and then show the CPS definitions it uses. 

roundclock . c The body of roundclock, implemented in the file roundclock . c, consists 

of a simple timed loop. The timer can be triggered either because the next unit of 
time has elapsed or because the News server has received a /Damaged event. 
When damage occurs, the UNIX process repaints the entire clock. When the next 
unit of time has elapsed, the UNIX process unpaints the old hands and paints the 
new hands. 

roundclock has two options. If the -s flag is specified, roundclock 
displays a second hand. If -f is specified, roundclock paints itself in a fancy 
way. 

^ ^ ^ ^ 

/■k 

^ News clock program 

#include <stdio.h> 

#include <sys/time.h> 

#include <sys/ioctl . h> 

#include "psio.h" 

#include "roundclock , h” 

#include <signal.h> 

int fancy_clock =0; 

main(argc,- argv) 

char ^^argv; 

{ 

int show_seconds =0/ 

int damaged; 

int second_hand_length = 38; 

int minute_hand_length =35; 

int hour_hand__length = 20; 

int Imin = Ihour = - 1 ^ Isec = -1; 

while ( — argc > 0) { 

if ( (++argv) [0] [0] == ) 
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switch (argv[0][l]) { 

case ' f' : 

fancy_clock = 1; 
break; 
case 's' : 

show_seconds = 1; 
break; 
default: 

fprintf (stderr^ "roundclock : illegal option : %s\n" , argv[C 
exit (-1) ; 

} 

else { 

fprintf (stderr^ "roundclock : illegal option : %s\n" , argv [ 0 ]) ; 
exit (-1) ; 

} 

} 

if (ps_open_PostScript ( ) == 0) { 

fprintf (stderr, "No NeWS server\n") ; 
exit (-1) ; 

} 

if (f ancy__clock) { 

second_hand_length =10; 
minute_hand_length = 35; 
hour_hand_length = 20; 
ps__f ancy__init ializeclock ( ) ; 

} else { 

ps_initializeclock ( ) ; 

} 

ps__createclock ( ) ; /* initialize round clock window */ 

while (1) { 

register struct tm *tm; 
long now = time(O); 

if (damaged) { /* Redraw the clock face if necessary */ 

ps__redrawclock ( ) ; 
damaged = 0 ; 

} 

tm = localtime (&now) ; 

ps_white(); /* Clear out the old hands */ 

tm->tm_hour = tm->tm_hour * 5 + tm->tm_min / 12; 
if (Imin >= 0) { 

if (tm->tm_min != Imin) 

hand (Imin, minute_hand_length) ; 
if (show_seconds && tm->tm_sec != Isec) 
handdsec, second_hand_length) ; 
if (tm->tm_hour != Ihour) 

handdhour, hour_hand_length) ; 

} 

ps_black(); /* draw the new hands */ 

if (show_seconds) 

hand (tm->tm_sec, second_hand_length) ; 
hand (tm~>tm_min, minute_hand__length) ; 
hand (tm->tm_hour, hour_hand_length) ; 

Isec = tm->tm sec; 
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Imin = tm->tm_min; 
Ihour = tm->tm_hour; 
ps_f lush_PostScript () 



( 



/* Wait for either the next clock tick or a 
window damage repair request '^ / 
int msk = 1 « psio_fileno (PostScript Input ) ; 

int n ; 

static struct timeval t; 

now = show_seconds ? 1 : 60 - tm->tm_sec; 
t«tv_sec = now > 60 ? 60 : now; 
if (select (32;- &msk, 0;- 0^ &t) > 0) { 

char buf [1000] ; 

n = read (psio_f ileno (PostScriptInput ) /- buf, sizeof buf ) ; 
if (n > 0) /* The only input the clock 

ever gets is a damage 
* repair request '^ / 



damaged++; 
else if (n === 0) 
exit (0) ; 

else 

perror ("read") ; 



hand (angle, radius) 

int angle, radius; 

{ 

if ( f ancy_clock) 

ps_fancy_hand (-angle * 6, radius) 

else 

ps_hand (-angle 6, radius); 



roundclock . cps 



All painting is done with POSTSCRIPT language routines defined with the help of 
the CPS library. The CPS definitions are contained in roundclock . cps. This 
file contains definitions of routines to create a round clock, to draw the clock 
frame and hands in a simple style, and to draw the clock frame and hands in a 
fancy style. 



% CPS PostScript definitions to support clocks, 
cdef ps_createclock ( ) 

/window framebuffer /new Def aultWindow send def 



{ 



/IconLabel (Clock) def 
/FixFrame { (F) print } def 

/PaintClient { (P) print } def 

/ShapeFrameCanvas { 

gsave ParentCanvas setcanvas 
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FrameX FrameY translate 
FrameWidth FrameHeight scale 

.5 .5 .5 0 360 arc FrameCanvas setcanvasshape 
grestore 

} def 

/ShapeClientCanvas { } def 

/CreateClientCanvas { 

/ClientCanvas FrameCanvas newcanvas def 
} def 

/PaintFrame { } def 

/PaintFocus { 

gsave FrameCanvas setcanvas 

KeyFocus? {KeyFocusColor ) {FrameFillColor } ifelse setcolor 
calctransf orm 0 0 40 0 360 arc stroke 
grestore 
} def 

} window send 

/reshapef romuser window send % Shape it. 

/map window send % Map the window. 

window /FrameCanvas get setcanvas 
/calctransf orm { 

initmatrix initclip 

clippath pathbbox 100 div exch 100 div exch scale pop pop 
50 50 translate 

} def 
/RDC { 

window /FrameCanvas get setcanvas 
damagepath clipcanvas 

calctransf orm drawclockf rame clipcanvas 

} def 

cdef ps__white() W 
cdef ps_black() B 
cdef ps__redrawclock ( ) RDC 

% 

% ps_hand draws a plain clock hand. 

o, 

o 

cdef ps_hand (rot , rad) 
gsave 

rot rotate 0 0 moveto 0 rad rlineto 
stroke 
grestore 

g, 

o 

% ps__fancy__hand draws a fancy clock hand. 

'6 

cdef ps_f ancy_hand (rot , rad) 
gsave 

rot rotate newpath -5 0 moveto 005 180 360 arc 
0 rad rlineto -5 5 rlineto -5 -5 rlineto closepath 
fill 



m, 
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grestore 

cdef ps_initializeclock ( ) 

/drawclockf rame { 

bordercolor setcolor clippath fill 
0 0 45 0 360 arc 
backgroundcolor setcolor fill 
text color setcolor 
12 { 

0 40 moveto 
0 5 rlineto 
stroke 
30 rotate 
} repeat 
} def 
/B { 

textcolor setcolor 
} def 
/W { 

backgroundcolor setcolor 
} def 



cdef ps_f ancy_initializeclock ( ) 

/drawclockf rame { 

.75 monochromecanvas {setgray} {.7 .7 setrgbcolor} ifelse fill 
clippath fill 

0 0 40 0 360 arc 

1 monochromecanvas {setgray} (1 1 setrgbcolor} ifelse fill 
1 monochromecanvas {setgray} {1 0 setrgbcolor} ifelse fill 

0 45 5 0 360 arc fill 
} def 

/B { 

.5 monochromecanvas {setgray} {.6 1 setrgbcolor} ifelse fill 
} def 
/W { 

1 monochromecanvas {setgray} {1 1 setrgbcolor} ifelse fill 
} def 

V ^ / 
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u 

News Type Extensions 



News extends the POSTSCRIPT language with a number of new types. Some are 
opaque and can be accessed only by their specific operators. Others can be 
opened and accessed like dictionaries. The keys available in these ‘ ‘magic dic- 
tionaries” are discussed in the following sections. Types that are opened as dic- 
tionaries are not, unless specially marked as such, read-only. 

11.1. New Objects in NeWS 

canvas canvas 

Canvas objects represent Cartesian coordinate spaces, with arbitrarily shaped 
boundaries. Each display is represented by a canvas; others may be created and 
arranged in an overlapping list. 

color color 

Color objects represent a color. They can be defined using either RGB or HSB 
coordinates; they can be compared; and they can be used as a source of paint for 
the rendering primitives. 

event event 

Event objects represent (a) messages between News processes and (b) input 
events from physical devices. Events can be accessed as dictionaries. 

graphicsstate graphicsstate 

Graphics state objects preserve entire graphics states, as defined by the 
PostScript language, in a permanent form. Their only use is to be saved and 
restored. 
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monitor monitor 

Monitor objects are used for mutual exclusion, A monitor object has 
piece of state indicating whe±er it is locked or unlocked. Processes can us 
monitors to implement mutual exclusion (for example, to prevent conflicts 
updating shared data stractures). 

process process 

Process objects represent lightweight processes in the POSTSCRIPT languag 
interpreter. They can be accessed as dictionaries. 

shape shape 

Shape objects represent paths, as defined by the POSTSCRIPT language, in i 
manent form. Their only use is to be saved and restored; only the current \ 
may be operated on. 

The internal state of some of these new types is accessible as if the object \ 
dictionary; fields in the object are accessed just like keys in a dictionary. I 
pies of typical usage (iJiese particular keys are discussed later) are: 

MyCanvas /Color get % determine if ‘MyCanvas’ is a colored 

or 

MyEvent /Name /EnterEvent put % set the Name in ‘MyEvent’ to EnterE 

CAUTION The use of new type objects as dictionaries has defined behavior oo^f 
existing keys given for each type. You should not define new key^^l 
“dictionaries”; the results are undefined and what happens may chan 
future implementations. 

The following sections describe the keys of interest in those types that are 
sible as dictionaries. 

NOTE In the header to the description of each key, the type to the left of the key h 
cates what values may be assigned to the key, and the type to the right indi 
what values may be retrieved. For read-only keys, the position to the left c 
tains 



11.2. Objects as 
Dictionaries 
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11.3. Canvases as 
Dictionaries 



TopCanvas 



BottomCanvas 



CanvasAbove 



CanvasBelow 



TopChiid 



Parent 



The accessible keys of a canvas dictionary are: 

TopCanvas 

BottomCanvas 

CanvasAbove 

CanvasBelow 

TopChiid 

Parent 

Transparent 

Mapped 

Retained 

SaveBehind 

Color 

EventsConsumed 

Interests 

They are dealt with in order below. 

- TopCanvas canvas 

The current canvas’ top sibling. The TopChiid of the parent canvas. 

- BottomCanvas canvas 

The current canvas’ bottom sibling. 

- CanvasAbove canvas or null 

The sibling canvas immediately above this canvas, or null if no such canvas 
exists. 



- CanvasBelow canvas or null 

The sibling canvas immediately below this canvas, or null if no such canvas 
exists. 



- TopChiid canvas or null 

The top child of this canvas, or null if no such canvas exists, 

canvas or null Parent canvas or null 

The parent of this canvas, or null if the canvas has no parent. Null is returned, 
for example, for canvases that result from createdevice. Setting this field mani- 
pulates the window hierarchy. 
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Transparent 



Mapped 



Retained 



SaveBehind 



Color 



EventsConsumed 



boolean Transparent boolean 

True if the canvas is transparent, false if it is opaque. An opaque canvas-vis 
hides all canvases underneath it; a transparent canvas does not. A transparei 
canvas never has a retained image; instead it shares its parents retained imag 

boolean Mapped boolean 

True if the canvas is mapped, false if it is unmapped. When a canvas is maj 
it becomes visible on the screen that its parent is on. When a nonretained w 
dow is mapped, the region that becomes visible is considered to be damaged 

boolean Retained boolean 

True if the canvas is retained, false if it is not. News keeps an offscreen cop 
a retained canvas. If it is on a screen and overlapped by some other canvas, 
hidden parts of the canvas will be saved. A retained canvas generally perfor 
much better with most window management operations, like moving and po 
ping canvases. But the retained image does consume storage. For color dis] 
the cost of retaining canvases is often prohibitive. 

boolean SaveBehind - 

SaveBehind is a hint to the window system that when the canvas is made vi 
on the screen canvases below it won’t be too active and the canvas won’t be 
too long. This is a performance hint only; it does not affect the semantics o1 
other operations. It is generally employed with popups to reduce the t 
damage repair when they are removed. 

- Color boolean 

True if and only if the current canvas can support more colors than just blac 
white, or greyscale. 

keyword EventsConsumed keyword 

The event consumption behavior of the canvas is determined by its 

EventsConsumed key, where keyword is one of: 

/AllEvents 

no events will be matched against canvases behind this one 
/MatchedEvents 

events that match an interest on this canvas will not be matched against 
canvases behind this one 

/NoEvents 

events will be matched against interests on canvases behind this one, re 
less of whether they match. 
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Interests 



11.4. Events as Dictionaries 



Action 



Canvas 



- Interests array 

The interest list for the canvas is returned as an array of events. The order of 
events in the array is the priority order of the interests, highest first. (The gio- 
balinterestlist primitive returns an exactly similar array of interests for the glo- 
bal interest list - the set of interests expressed with a null Canvas. It is defined in 
Chapter 1 2, NeWS Operator Extensions), 

The currently accessible keys of an event dictionary are: 

Action 

Canvas 

ClientData 

Exclusivity 

Interest 

Isinterest 

IsQueued 

KeyState 

Name 

Priority 

Process 

Serial 

TimeStamp 

XLocation 

YLocation 



object Action object 

An arbitrary POSTSCRIPT language object, often depending on the value of the 
Name. For keystrokes, the value of Action is /DownTransition or /UpTransi- 
tion; for mouse motion. Action is null, etc. 

In an interest, the Action may be a number, a keyword, or a string, in which case 
it is matched exactly against the Action of candidate events; or the Action may 
be an array or dictionary. See Chapter 3, Input, for more information on interest 
matching. 

null or canvas Canvas null or canvas 

When an event is submitted for distribution (by sendevent or redistributeevent), 
this key indicates a restriction on its distribution: the event only matches interests 
expressed with respect to the given canvas. Certain system events (such as 
/Damaged events) have a canvas specified. 

In an interest, the Canvas specifies that only events that happen to that canvas 
will be matched. Null in an interest Canvas indicates an interest in all events not 
explicitly directed to a particular canvas. 



• sun 

XT microsystems 



Revision A of 15 January 1988 




122 NWS 1.1 Manual 



object ClientData object 

In either an interest or an event submitted for distribution, this field may'^idk 
additional information relating to the event. The information is carried alon; 
without modification by NeWS. 

boolean Exclusivity boolean 

Exclusivity is meaningful only for interests, although it may be set and read 
any event (since any event may be used as an argument to expressinterest). 
true, it indicates that an event that matches this interest in distribution shoulc 
be allowed to match any further interests. 

- Interest event 

This read-only key is set in a real event as it is distributed; its value is the ini 
that the event matched in order to be delivered to its recipient. 

- Isinterest boolean 

This read-only key indicates whether an event is currently on some interest 1 

- IsQueued boolean 

This read-only key is tnie when the event has been but in the input queue an' 
not yet been delivered. 

KeyState - KeyState array 

When keyboard translation is on, this array is empty. When translation is of 
this array indicates all tlie keys that were down at the time the event was dist 
bated. (Normally, liteUI . ps is loaded by the server at initialization ano 
turns off translation to gain access to the unencoded Sun keyboard.) The arr 
actually contains the Name values from events that had an Action of /Down 
Transition, and that did not have a subsequent event with the same Name a; 
Action of /UpTransition. In generating this array, the test is executed befoi 
down-event, and after an up-event, so a down-up pair with no intervening ev 
will not be reflected in the KeyState array. 

This key is meaningless in an interest. 

Name object Name object 

An arbitrary POSTSCRIPT language object, generally indicating the kind of e 
For example, keystrokes will have numeric Names corresponding to the AS( 
characters (or the keys) that were pressed. Many other events have keyword 
values, such as /Damaged or /EnterEvent. 

In an interest, the Name may be a number, a keyword, or a string, in which c 
it is matched exactly against the Name of candidate events; or it may be an ; 
or dictionary. See Chapter 3, Input, for more information on interest matchi 



ClientData 



Exclusivity 



Interest 



Isinterest 



IsQueued 
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Priority number Priority number 

Priority is meaningful only for interests, although it may be set and read in any 
event (since any event may be used as an argument to expressinterest). Real 
events are matched against the interests expressed on a canvas in priority order, 
highest priority first; among interests with the same priority, the most recent is 
considered first. For these purposes, the global interest list (interests expressed 
with a null Canvas) is treated like the foremost canvas interest list. The default 
priority is 0; fractional and negative values are allowed, and there are very few 
circumstances where the priority need be changed at all. 

Process null or process Process null or process 

In the event queue, this key indicates the only process the event will be delivered 
to (if any — it must still match on all other criteria). In an interest list, it 
identifies the process that expressed this interest. 



Serial - Serial number 

This key is a number that reflects the order in which events are taken off the 
event queue. For an interest. Serial equals the serial number of the last delivered 
event that matched this interest. This is a read-only key. 



Times tamp 



number TimeStamp number 



The current nominal resolution of a 
time value is 2’'® seconds (about 
0.9 ms) and the maximum interval 
is 65,536 minutes (about 45'/2 
days). 



This numeric value indicates the time an event occurred. (A time value is simply 
the number of minutes since the system started; it may contain a fractional com- 
ponent.) Events in the event queue are distributed in TimeStamp order, and no 
event is delivered before the time in its TimeStamp field. Thus, a timer event is 
simply any event handed to sendevent with a TimeStamp value in the future. 
This key is ignored in interests. 



XLocation 



YLocation 



11.5. Graphics States as 
Dictionaries 



number XLocation number 

System events are labeled with the cursor location at the time they are generated; 
this value is used to determine which canvas(es) the event can be distributed to. 

It is available to recipients and is transformed to the current canvas’ coordinate 
system. This key accesses the X-coordinate of the location. It is ignored in 
interests. 

number YLocation number 

This key accesses the Y-coordinate of the event location; see the explanation 
under XLocation above. It is ignored in interests. 

Graphics state objects are intended to be opaque. Their only use is to save the 
graphics state of a process for future re-use by that (or another) process. They 
are, therefore, not accessible as dictionaries. 
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11.6. Processes as 
Dictionaries 



DictionaryStack 



ErrorCode 



The keys that may be accessed in a process dictionary are: 

DictionaryStack 

ErrorCode 

StandardErrorNames 

ErrorDetailLevel 

Execee 

ExecutionStack 

Interests 

OperandStack 

State 

All of these keys are read-only; attempts to change their values in a process 
unregistered errors. 

- DictionaryStack array 

The current dictionary stack of the process is returned as an array. The earli 
dictionary is array element 0. 

- ErrorCode keyword 

The current errorcode of the process is returned as a keyword. The set of pc 
ble results is 

/accept 

/dictfull 

/dictstackoverflow 

/dictstackunderflow 

/ execstacko verflow 

/interrupt 

/invalidaccess 

/invalidexit 

/invalidfileaccess 

/invalidfont 

/invalidrestore 

/ioerr 

/killprocess 

/limitcheck 

/nocurrentpoint 

/none 

/rangecheck 

/stackoverflow 

/stackunderflow 

/syntaxerror 

/typecheck 

/undefined 

/undefinedfilename 

/undefinedresult 

/unimplemented 

/unmatchedmark 

/unregistered 

/VMerror 
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V 

StanclardErrorIvatties 



ErrorDetail Level 



Execee 



ExecutionStack 



Interests 



OperandStack 



State 



- Standard ErrorNames array 

StandardErrorNames is an array of the names of the standard errors. It is used 
by errored and the debugger, and is available for other programs’ use. 

process ErrorDetail Level - 

Controls the amount of detail that is included in an error report. Setting Error- 
DetailLevel to 0 (the default) gives a minimum of error reporting. Setting it to 1 
yields a more descriptive message, to 2 dumps the contents of the dictionary, 
execution and operand stacks. Setting the detail level is done as follows: 
^ 

currentprocess /ErrorDetailLevel 1 put 

v.^ J 

- Execee object 

The object currently being evaluated (i.e., the top of the process’ execstack) is 
returned. 

- ExecutionStack array 

The full current execution stack of the process is returned as an array, containing 
pairs of executable arrays and indices. The latest executable array is element 0 of 
the array, the “program counter’’ within it is element 1. 

- Interests array 

The current interest list of the process is returned as an array. The first element 
of the array is the event which is the most recently expressed interest in this pro- 
cess. 

- OperandStack array 

The full current operand stack of the process is returned as an array. The earliest 
object on the stack is element 0. 

- State array 

The current execution state of the process is returned as a keyword. The set of 
possible results is: 

/breakpoint 

/dead 

/inputwait 

/IO_wait 

/monwait 

/procwait 

/runnable 

/zombie 
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11.7. Shapes as 
Dictionaries 

11.8. Object Cleanup 
Server Function 



Shape objects are opaque. Their only use is to save the current path of 
for future re-use by that (or another) process. They are, therefore, not access 
as dictionaries. 



The following sections in this heading discuss how to manage object cleanuf 
connections and processes. These discussions are directed towards applicatio 
developers. 

When News starts, it runs the code in init . ps called /server. This launch 
process that listens for connections requests on a well-known socket^ Each 
request for a new client forks a new process which is its initial process. Witl 
that process is a small code fragment that: 

□ makes this process a member of a new process group 

□ builds the client’s userdict 

□ initializes the graphics state. 

The following code does all this: 

^ 

1 00 diet begin initmatrix newprocessgroup 





Finally, the client code is executed by executing; 



/ — 

connection file CVX exec 




This converts the connection file to executable and then executes it. It return 
when the socket is closed by the client. 

Any client which has made entries in systemdict that should be cleaned up 
should do so before killing the client processgroup. This can be done by ove 
riding the DestroyCIient method in the client window or by catching the ei 
on the client socket. 

This latter is done by starting a recursive file read in the client process. (See 
description above of how the client process is initialized) This is done by ha 

the CPS initialization program include the following; 
— 

edef initializeO 

/AbortProc {..do cleanup here..} def 
/NestedServer (currentfile cvx exec AbortProc} def 

/win framebuffer /new DefaultWindow send def 

NestedSeiver 
edef ... 





” Seethe news_server (1) manual page fora more complete discussion. 
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The client will have altered the /NestedServer loop to add the additional process 
/AbortProc. This code will be executed in the initial client process when the 
socket is closed^^. 

Object Management There is no way to determine all the objects that the server thinks are being refer- 

enced, The reason for this is that there is currently no way to enumerate all the 
processes known to the server. Because of this, there is no way to get at the dic- 
tionaries that are “private” to these, mainly their userdict. Thus the best one can 
do is enumerate all objects visible to systemdict. 

There are ways, however, for a given client to allow for its objects to be 
enumerated. The simplest way is to put hooks in systemdict. One way would be 
to have clients put process objects in a dictionary in the systemdict. Using a dic- 
tionary (rather than a composite object) would confer the benefit of precluding 
duplicate entries. Another way is to have each process listen for special events 
from other processes^ 

Clients can do much of their own error processing by using their own version of 
errordict. (PostScript language error handling is discussed in detail in the 
PostScript Language Reference Manual.) There is a set of standard error names 
in systemdict. There is also a simple utility, errored that uses these. 

Client side errors are dependent on their environment. C clients have to do most 
of their own error-handling. The C client can catch signals and can install a 
cleanup proc for their server connection using the AbortProc and NestedServer 
(discussed above under the section titled Server Function . 

Connection Management If a C program is terminated without calling ps_close_Post Script the 

client UNIX process will terminate, closing all its file descriptors. This in turn 
will close the socket being used by the NeWS server for that process. This will 
behave much like calling ps_close_PostScript, in that the client process 
in the server will terminate. See the discussion on the initialization of the client 
process, and the AbortProc and NestedServer programs. 

Process Management The key to process management is to insure that memory reclamation is efficient. 

Garbage collection should automatically clean up virtual memory when an appli- 
cation is killed. 

Killing An Application An application should kill its process groups and any other process groups it has 

created upon its own termination. The News server does this when your client 
socket closes^"^. The psh client creates a new process group so that the closing 
of the client socket does not automatically kill the client. Otherwise, all psh 
clients would always immediately die as soon as their window was created. 

Some resources, such as cached fonts, are considered system resources and are not under client control. 

Windows are redrawn in the lite tool kit using this method. 

If you are running as a simple PostScript language only program using the psh shell, the Zap menu item 
will also, by default, kill the its process group. 





Revision A of 15 January 1988 




128 



NWS 1.1 Manual 



Garbage Collection Garbage collection is the process of removing objects from virtual men^ % 

they are no longer referenced. The problem is quite acute in the current gene 
tion of printers that understand the POSTSCRIPT language and any virtual 
memory system must cope with it. Killing the client process group will “den 
ence” the client’s userdict, which will recursively garbage collect all the die 
local references. When the main process dies, it kills its process group. Only 
other process groups have been created is there a need to explicitly kill the f( 
processes made by that group. 

When a process dies, the various stacks associated with it are garbage collec 
(their ref count decremented). The dictionary stack, in particular, will have e 
entry decremented. If a forked process created a dictionary and put it on its c 
tionary stack, the only reference will be that of the process’ dictionary stack. 
Thus that dictionary will be garbage collected. Then, any objects in that diet 
ary will then also be dec-reffed, making them candidates for garbage collect! 

In other words, objects will be garbage collected only when all references to 
them go away, regardless of the process dying. De-referencing a dictionary 
references all the objects in the dictionary when the dictionary is garbage co 
lected. When a composite object (arrays and dictionaries) is garbage collecte 
each of its elements decreases its refcount and is in turn garbage collected if 
count has gone to zero. 

11.9. News Security There is a dictionary called RemoteHostRegistry maintained in the seng^v 

keys are the names of hosts which are allowed to connect to the NeWS 
When News starts up, this just contains the name of the local host. Wheneve 
connection is attempted, the name of the remote host is checked to see if it ii 
this dictionary, and if it isn’t then a message is issued to the user and the cor 
tion is closed. 

NOTE This is exactly the same security that the X window system has. 

A variable in the systemdict named NetSecurityWanted may be set to falst 
disable this security mechanism. 

The shell script newshost(l) allows you to manage the registry of permits 
host names from the command line. 



De-Referencing Composite 
Objects 
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c 



acceptconnection 



activate 



arccos 



arcsin 



arctan 




News Operator Extensions 



- X - 

Mercilessly abort the News server. (The name consists of two characters — a 
followed by a ‘C’ — not a control-C.) 

listenfile acceptconnection file 

Listens for a connection from another UNIX process to the NeWS server on 
listenfile. When another process connects, will connect the server with the 
client. Things that the client writes to the server will appear on file, and things 
written to file will be sent to the server. Listenfile is created by invoking file with 
the special file name (%socketln). Af is the IP port number that will be used 
for listening. 

proc activate process 

Creates a new process that will be executing proc in an environment that is a 
copy of the original process’s environment. When proc exits, the process will 
terminate. Process is a handle by which the newly created process can be mani- 
pulated. 

See also: killprocess, killprocessgroup , waitprocess 

num arccos num 

Computes the arc cosine in degrees of num. 

num arcsin num 

Computes the arc sine in degrees of num. 

num arctan num 

Computes the arc tangent in degrees of num. You should probably use atan 
instead. 
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awaitevent 



blockinputqueue 



breakpoint 



buildimage 



- awaitevent event 

Blocks the News lightweight process until an event in which it has exprdfc^ 
interest happens, and returns an object of type event describing it. 

See also: blockinputqueue, createevent , expressinterest , redistributeevent , 
sendevent 

num blockinputqueue - 

Inhibit distribution of input events from the event queue, until a correspondii 
unblockinputqueue is executed, or num minutes, whichever happens first. 
When calls to blockinputqueue are nested, the timeout goes until the last of 
of them and the queue remains blocked until an unblockinputqueue has bee 
executed to match each blockinputqueue. 

Events used as arguments to sendevent are inserted in the event queue, and 
hence are subject to inhibition; events passed to redistributeevent are not re 
queued, and so are not ijihibited. 

See also: sendevent, unblockinputqueue 



- breakpoint - 

Suspends the current process. 

width height bits/sample matrix proc buildimage canvas 
Constructs a canvas object from the width, height, bits! sample, and prot^t^v. 
ters in the same way as image interprets its parameters. A notable diffC^o 
between the Sun and Adobe implementations is that if bits/ sample is 24 ther 
image is interpreted as color. The inverse of the matrix is used to define the 
default coordinate system of the canvas. 

The parameters represent a sampled image that is a rectangular array of widi 
height sample values, each of which consists of bits! sample bits of data (1,8 
The data is received as a sequence of characters (i.e., 8-bit integers in the rai 
to 255). If bits! sample is less than 8, the sample bits are packed left to right 
within a character (from the right-order bit to the low-order bit). Each row i 
padded out to a character boundary. 

The buildimage operator executes proc repeatedly to obtain the actual imag 
data. Proc must return (on the operand stack) a string containing any numb( 
additional characters of sample data. 

The matrix parameter specifies the transformation from a unit square to the ] 
coordinates of the image. 

NOTE In the current implementation, only matrices of the form [width 0 0 -height i 
height] will work correctly. 
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canvastobottom 



canvastotop 



clipcanvas 



clipcanvaspath 



continueprocess 



contrastsvvithcurrent 



copyarea 



canvas canvastobottom - 

Moves the canvas to the bottom of its list of siblings. 

canvas canvastotop - 

Moves the canvas to the top of its list of siblings. 

- clipcanvas - 

The clipcanvas operator is similar to clip except that it sets a clipping boundary 
that is an attribute of the current canvas, not the current graphics state. This clip- 
ping boundary is not affected by initgraphics, initclip, gsave, grestore, or any 
of the other graphics state modifiers. Graphics operations are clipped to the 
intersection of the canvas clip, the graphics state clip, and the shape of the can- 
vas. 

It is intended to be used when it is necessary to impose clipping restrictions on 
all operations aimed at a canvas, no matter where they come from. This is typi- 
cally used during damage repair to restrict updates to the damaged region. 

The clip path set by this operation is not the clip path manipulated by the opera- 
tions clip, clippath, eoclip, and initclip. The initclip operator sets its clip path 
to the shape of the canvas. 

See also: damagepath, clipcanvaspath 

- clipcanvaspath - 

Sets the current path to the canvas clipping for the current canvas as set by clip- 
canvas. 

process continueprocess - 

Restarts a suspended process. 

See also: suspendprocess, breakpoint 



color contrastsvvithcurrent boolean 

Returns true if the color argument is different than the current color. The test 
takes into account the characteristics of the current device. The standard boolean 
operators, like eq can be used to compare colors without accounting for the 
current device. 



dx dy copyarea - 

Copies the area enclosed by the current path to a position offset by dx,dy from its 
current position. For example, you could use this primitive to scroll a text win- 
dow. The nonzero winding number mle is used to define the inside and outside 
of the path. 
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countinputqueue 



createdevice 



createevent 



createmonitor 



createoverlay 



currentautobind 



- countinputqueue num 

Returns the number of e vents currently available from the POSTSCRIPT 
process’ input queue. If this number is positive, awaitevent will not block. 

string createdevice canvas 

Creates a new canvas from a frame buffer device named by string. The usut 
value for string on a Sun is “/dev/fb.” 

- createevent event 

Synthesizes an object of type event, which will have null or zero values for t 
fields. 

See also: awaitevent, redistributeevent , expressinterest , sendevent 

- createmonitor monitor 

Creates a new monitor object. 

See also: monitorlocked, monitor 

canvas createoveriay canvas 

Given a canvas, createoverlay creates a new canvas that overlays the origin 
An overlay is like a sheet of cellophane that lays over a canvas. Anytliing tf 
drawn in an overlay will float over the underlying canvas. Objects drawn in 
overlay will not affect the underlying image, and objects drawn in the tp^r 
image will not affect the overlay. Because of the way that overlays are'tepl 
mented on some displays, there will be performance problems if too many tl 
are written into the overlay. They are intended to be used for animated obje 
like rubber band lines and bounding boxes. 

The current color is usually ignored when drawing in overlays. They will gi 
erally be done in black. This weakness in the specification of overlays is an 
explicit feature: it’s there to allow overlays to be implemented using a variei 
tricks on different types of hardware. 

NOTE In the current implementation, if there are multiple overlays active on the sc 
only one of them will be visible, chosen essentially at random. 



- currentautobind boolean 

Returns true or false depending on whether or not autobinding is enabled foi 
current process. 

See also: setautobind 
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currentcanvas 



currentcolor 



currentcursorlocation 



currentiinequality 



currentpath 



currentprintermatch 



currentprocess 



currentrasteropcode 



- currentcanvas canvas 

Returns the current value of the canvas parameter in the graphics state. 

- currentcolor color 

Returns the current color as set by setcolor, setrgbcolor, or sethsbcolor. 

- currentcursorlocation x y 

currentcursorlocation returns the cursor’s position at the time of the last event 
distributed from the input queue. 

- currentiinequality n 

Returns an integer between 0 and 1 that represents the desired line quality. 

See also: setlinequality 

- currentpath shape 

Returns an object of type shape that describes the current path. It may later be 
passed to setpath. 

- currentprintermatch boolean 

Returns the current value of the printermatch flag in the graphics state. 

See also: setprintermatch 

- currentprocess process 

Returns an object that represents the current process. 

- currentrasteropcode num 

Returns a number that represents the current rasterop combination function. 

See also: setrasteropcode 

NOTE The RasterOp combination function exists only to support emulation of existing 
window systems. If you find yourself using it, you are probably making a mistake 
and will have problems running your programs on a wide range of displays. The 
definition of rasterop is display-specific. Currently the image and copyarea 
primitives do not use the rasteropcode. 
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currentstate - currentstate state 

Returns a graphicsstate object that is a snapshot of the current graphic^scSt 
See also: setstate 



- currenttime num 

Returns a time value n.nnn in minutes since some unspecified starting time, 
only guarantee that is made about the value returned by currenttime is that 
difference of the results of two successive calls is approximately the numbei 
minutes that have elapsed in the interval of time between them. 

- damagepath - 

Sets the current path to be the damage path from the current canvas. The da 
path will be cleared. The damage path represents those parts of the canvas t 
were damaged by some manipulation of the scene on the display, and that C( 
not be repainted from stored bitmaps. Processes can arrange to be notified c 
damage through the input mechanism. Whenever damage occurs to a canva 
Damaged event will be generated, 
clipcanvas 

dumpsys - dumpsys - 

Dumps the contents of the system state to the standard output file. Output ie 
quite voluminous and is interesting only to persons who are debugging the 
server. 

emptypath - emptypath boolean 

Tests the current path, returning true if it is empty. 



currenttime 



damagepath 



See also: 



enumeratefontdicts 



enumeratefontdicts names 



PostScript language code should 
use FontDirectory in preference! to 
enumeratefontdicts. 



Scans through all the font dictionaries that NeWS knows about and pushes thi 
family file name onto the stack (of each font family that it can find). 



eoclipcanvas - eoclipcanvas 

This is the same as clipcanvas except that it uses the even/odd winding nurr 
mle rather than the nonzero rule. 

See also: clipcanvas 
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eocopyarea 



eocurrentpath 



eoreshapecanvas 



eowritecanvas 



eowritescreen 



expressinterest 



dx dy eocopyarea - 

Copies the area enclosed by the current path to a position offset by dx,dy from its 
current position. For example, you could use this primitive to scroll a text win- 
dow. The even/odd winding number rule is used to define the inside and outside 
of the path. 

See also: copyarea 

- eocurrentpath shape 

Returns an object of type shape that describes the current path using the even/odd 
rule. 

See also: currentpath 

canvas eoreshapecanvas - 

The eoreshapecanvas operator is identical to reshapecanvas except that it uses 
the even/odd winding number rule to interprete the path. 

See also: reshapecanvas 



file or String eowritecanvas - 

Either opens string as a file for writing, or if the argument is a file simply writes 
to it. Creates a rasterfile which contains an image of the region outlined by the 
current path in the current canvas. If the current path is empty, the whole canvas 
is written, eowritecanvas would be used to save an image in a file, eowritecan' 
vas follows an even-odd winding rule rather than a non-zero winding rule. 

See also: writecanvas, writescreen , eowritescreen 



file or String eowritescreen - 

Either opens string as a file for writing, or if the argument is a file simply writes 
to it. Creates a rasterfile which contains an image of the entire screen, eowri- 
tescreen writes pixels from the screen, and it will include pixels from canvases 
that overlap the current canvas. If the current path is empty, the whole canvas is 
written, eowritescreen would be used to do a conventional screen dump, eowri- 
tescreen follows an even-odd winding rule rather than a non-zero winding rule. 
See also: writecanvas, writescreen , eowritecanvas 

event expressinterest - 

Input events matching event will be queued for reception by awaitevent. See 
Chapter 3, Input, for more information on interest matching. 

See also: awaitevent, createevent , redistributeevent , revokeinterest , sendevent 
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extenddamage 



eoextenddamage 



file 



forkunix 



getcanvascursor 



getcanvaslocation 



getenv 



- extenddamage - 

Add the current path to the damage shape for the current canvas. A /Da^iag 
event will be sent to those processes which have expressed interest. Uses thi 
non-zero winding rule. 

- eoextenddamage - 

Add the current path to the damage shape for the current canvas. A /Damag 
event will be sent to those processes which have expressed interest. Uses thi 
even-odd winding rule. 

stringl string2 file file 

Identical to the Adobe POSTSCRIPT interpreter implementation, with one exi 
tion: if the file identified by stringl cannot be found, and it is not an absolute 
pathname, the server will attempt to open the file $NEWSHOME/ lib/^mVi 

String forkunix - 

Forks a UNIX process to execute string as a shell command line. Standard i 
and output are directed to /dev/null. 

canvas getcanvascursor font char char 

Gets the cursor identifiers for canvas. Font is the font where the cursor ima 
characters (primary and mask) are stored. The first char is used as the 
locate the primary image and the second char is used to locate the masWsni 
See also: setcanvascursor 



canvas getcanvaslocation x y 

Returns the location of canvas relative to the current canvas. X,y is a delta ^ 
(offset) in the current coordinate system from the lower left-hand comer of i 
current canvas to the lower left-hand comer of canvas. 

See also: movecanvas 

String! getenv string2 

Returns the value of the variable stringl in the environment of the server pr 
as modified by any putenv operations. This operator fails with an undefinei 
error if stringl is not present in the environment. One can guard against thi 
by using the stopped operator to recover from the error. For example; 

{ (ENV) getenv } stopped { pop (env default) } if 
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geteventlogger - geteventlogger process 

Returns the process which is the current event logger, or null if there is none. 



getkeyboardtranslation - getkeyboardtranslation bool 

getkeyboardtranslation returns a boolean, true means the kernel is interpret- 
ing the keyboard; false means keyboard interpretation is being left to 
PostScript language code, as in liteUI. 

See also: keyboardtype, setkeyboardtranslation 

NOTE Specific to the Sun Operating System Interface; should eventually move into an 
environment dictionary. 



getmousetranslation - getmousetranslation boolean 

Returns true or false as the underlying operating system is or is not doing transla- 
tion and scaling on the input received from the mouse. Events from the mouse 
will have the following keyword values in their name fields depending on the 
value of mouse translation; 

Table 12-1 Mouse Event Translation 



true 


false 


MouseDragged 

LeftMouseButton 

MiddleMouseButton 

RightMouseButton 


RawMouseDragged 

RawLeftMouseButton 

RawMiddleMouseButton 

RawRightMouseButton 



At present, there is no use for untranslated mouse events. 

NOTE Specific to the Sun Operating System Interface; should eventually move into an 
environment dictionary. 



getsocketlocaladdress file getsocketlocaladdress string 

Returns a string that describes the local address of the file. File must be a socket 
file, and will generally be a socket that is being listened to. This is generally 
used by servers to generate a name that can be passed to client programs to tell 
them how to contact the server. The format of the string is unspecified. 

getsocketpeername file getsocketpeername string 

Returns the name of the host that file is connected to. File must be an IPC con- 
nection to another process. Such files are created with either acceptconnection 
or (%socket) file. This is generally used with currentfile to determine where a 
client program is contacting the server from. 
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globalinterestlist 



hsbcolor 



imagecanvas 



imagemaskcanvas 



i nser tcan vasa bo ve 



- globalinterestlist array 

Returns an array of events which are the interests currently expressed wmi a 
Canvas field by all processes. The array is in priority order; the first element 
the array has the highest priority. 

h s b hsbcolor color 

Takes three numbers between 0 and 1 representing the hue, saturation, and 
brighmess components of a color and returns a color object that represents tf 
color. 

canvas imagecanvas - 

Renders a canvas onto the current canvas. It is much like the image operate 
except that the image comes from a canvas instead of a POSTSCRIPT languag 
procedure. 

The canvas is imaged into the unit square in user coordinates with (0,0) at th 
lower left-hand comer and (1,1) at the upper right-hand corner. To image a i 
vas at a particular place, merely set the CTM to position the unit square, just 
you would with the image primitive. 

The imagecanvas primitive deals with all scaling and technology mapping 
issues. It will, for example, map 24-bit color images onto black and white 
screens by dithering. 



boolean canvas imagemaskcanvas - 

Renders a canvas onto the current canvas. It is much like the imagemask o 
tor except that the image comes from a canvas instead of a POSTSCRIPT lang 
procedure. The boolean determines whether the polarity of the mask canvas 
be inverted. 

The canvas is imaged into the unit square in user coordinates with (0,0) at th 
lower left-hand comer and (1,1) at the upper right-hand corner. To image a 
vas at a particular place, merely set the CTM to position the unit square, just 
you would with the image primitive. 

canvas x y insertcanvasabove - 

Inserts the current canvas above canvas, using the same interpretation of [x 
movecanvas. The current canvas must either be a sibling or child of canvas 
The mapped attribute of the canvas does not change. 
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insertcanvasbelow 



keyboardtype 



killprocess 



killprocessgroup 



lasteventtime 



localhostname 



max 



min 



monitor 



canvas x y insertcanvasbelow - 

Inserts the current canvas below canvas, using the same interpretation of [x,y] as 
movecanvas. The current canvas must either be a sibling or child of canvas. 
The mapped attribute of the canvas does not change. 

- keyboardtype number 

Returns a small integer indicating the kind of keyboard attached to the News 
server. The return value is actually the return from the KIOCTYPE ioctl, docu- 
mented under kb(4S). 

See also: getkeyboardtranslation, setkeyboardtranslation 

NOTE Specific to the Sun Operating System Interface; should eventually move into an 
environment dictionary. 

process killprocess - 

Kills process. 

process killprocessgroup - 

Kills process and all other processes in the same process group. 

See also: newprocessgroup 

- lasteventtime num 

Returns the TimeStamp of the last event delivered by the input system. 



- localhostname string 

Returns the network hostname of the host on which the server is running. 

a b max c 

Compares a and b and leaves the maximum of the two on the stack. Works on 
any data type for which gt is defined. 

ab min c 

Compares a and b and leaves the minimum of the two on the stack. Works on 
any data type for which gt is defined. 

monitor procedure monitor - 

Executes procedure with monitor locked (entered). At most one process may 
have a monitor locked at any one time. If a process attempts to lock a locked 
monitor it will block until the monitor is unlocked. If an error occurs during the 
execution of procedure and the execution stack is unwound beyond the monitor, 
then the monitor object will be unlocked. 

See also: createmonitor, monitorlocked 
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monitorlocked monitor monitorlocked boolean 

Returns true if the monitor is currently locked; false otherwise. 

See also: createmonitor, monitor 

movecanvas x y movecanvas - 

Moves the current canvas to {x,y) relative to its parent. {x,y) is a delta vecto 
interpreted according to the current transformation. This motion is relative 
lower left-hand comer of the two canvases - (0,0) interpreted with referenct 
the initial matrix for each canvas. The mapped attribute of the canvas does 
change. 

See also: getcanvaslocation 

newcanvas pcanvas newcanvas ncanvas 

Creates a new empty canvas, ncanvas, whose parent is pcanvas. 

These defaults are the result o' his- It defaults to being opaque if its parent is the framebuffer; transparent other 

to rical precedent. To ensure the jj, defaults [q being retained if it is opaque and the number of bits per pixel ( 

portability of your programs to ^ r'r 

future releases of the system, vou framebuffer is less that the retain threshold. If your program relies on havir 

should always explicitly set the canvas be retained you should explicitly set it to be retained. 

Transparent property of all nev/ 

canvases. ,, , , 

See also: reshapecanvas 

newprocessgroup - newprocessgroup - 

Creates a new process group with the current process as its only memb^r.^ \ 
a process forks the child will be in the same process group as its parent. 

pathforallvec array pathforallvec - 

The single argument to pathforallvec is an array of procedures. The path- 
forallvec operator then enumerates the current path in order, executing one 
procedures out of the airray for each of the elements in the path. The type o 
path element determines which array element will be executed, moveto. Hr 
curveto, and closepath, respectively, are array elements 0, 1,2, and 3. If tl 
array is too short, pathforallvec will try to reduce elements of one type to 
another. Array element 5 is used to handle conic control points. The stand; 
PostScript language operator pathforall is exactly equivalent to ‘4 array 
astore pathforallvec.’ For further information, consult the PostScript Lan 
Reference Manual description of the pathforall operator. Users are cautior 
against using this primitive if at all possible, and using pathforall instead. 
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pause 



pointinpath 



putenv 



random 



readcanvas 



recallevent 



redistributeevent 



Chapter 12 — News Operator Extensions 1 43 



- pause - 

Suspends the current process until all other eligible processes have had a chance 
to execute. 

X y pointinpath boolean 

Returns true if the point [x,y] is inside the current path, 

stringl string2 putenv - 

Defines the shell environment variable stringl to have the value stringl. The 
environment variables inherited by the server as modified by putenv calls are 
inherited by UNIX processes created as children of the server with forkunix. 



- random num 

Returns a random number in the range [0,1]. 

String or file readcanvas canvas 

Reads a sun raster file into a newly created canvas (see the Pixrect reference 
manual). The argument to readcanvas should be a file object or a string. The 
canvas is either read from the file object or from the file named by the string. The 
string must be the name of a file in the server’s file name space. The canvas that 
is created will be retained and opaque. The canvas will have the depth specified 
in the raster file, will not have a parent, and will not be mapped. The canvas can- 
not be mapped; an invalidaccess error will result if you try to map the canvas. 
The canvas is useful only as a source for imagecanvas. If the file can’t be found, 
an undefinedfilename error is generated. If the file can’t be interpreted as a ras- 
ter file, an invalidaccess error is generated. 

event recallevent - 

The event passed as an argument is removed from the event queue. The most 
common use for this primitive is to turn off a timer-event that has been sent but 
not yet delivered. 

See also: sendevent 



event redistributeevent - 

Return an event that has been received by the calling process to the distribution 
mechanism, which will continue as though the event had not matched the interest 
which gave it to this process. 

See also: expressinterest 




nnicrosystems 



Revision A of 15 January 1988 




144 News 1.1 Manual 



reshapecanvas 



revokeinterest 



rgbcolor 



sendevent 



setautobind 



setcanvas 



canvas reshapecanvas - 

Sets the shape of canvas to be the current path, and it sets the canvas’ deraul 
transformation matrix from the current transformation matrix. This also est; 
lishes its position relative to the current canvas. If canvas is the same as the 
current canvas, then an implicit initmatrix will be done. The entire content 
the canvas is considered to be damaged. 

The initclip operation will set the path to the shape defined by the shape of , 
current canvas. 

Think of the current transformation matrix as laying down a grid over the ci 
path. This grid has its origin somewhere relative to the path and it has some 
scale, rotation, and skew associated with it. When reshapecanvas sets the 
default transformation matrix for the canvas, it sets it so that this same grid 
laid over the canvas as is laid over the current path, with the origin in the sa 
relative location. 

event revokeinterest - 

No more input events matching event will be distributed to this NeWS proces 
See also: expressinterest 

r g b rgbcolor color 

Takes three numbers between 0 and 1 representing the red, green, and blue i 
ponents of a color and returns a color object that represents that color. 

event sendevent - 

Submit an event to the input distribution mechanism (i.e., sort it into the evi 
queue according to its TimeStamp). See Chapter 3, Input, for more inform 
about event distribution. 

See also: awaitevent, createevent , recallevent , redistributeevent , expressintere: 

boolean setautobind - 

Enables or disables autobinding for the current process. By default it is on. 
Section 13.4, Autobind, for more information on autobinding. 

See also: currentautobind 



canvas setcanvas - 

Sets the current canvas to be canvas. Implicitly executes newpath initmati 
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setcanvascursor 



setcolor 



setcursorlocation 



seteventlogger 



setfileinputtoken 



setkeyboardtranslation 



font char char setcanvascursor - 

Sets the cursor identifiers for the currentcanvas. Font is the font where the cursor 
image characters (primary and mask) are stored. The first char is used as the 
index to locate the primary image and the second char is used to locate the mask 
image. 

See also: getcanvascursor 

color setcolor - 

Sets the current color to be color. The operation rgbcolor setcolor is the same 
as setrgbcolor, and hsbcolor setcolor is the same as sethsbcolor. 

X y setcursorlocation - 

Moves the cursor so its hot spot is at (x, y) in the current canvas’ coordinate 
space. 

process seteventlogger - 

Process (which must have expressed some interest — it doesn’t matter what) is 
made to be the event-logger. Thereafter, a copy of every event that enters the 
distribution mechanism will be given to this process prior to (and without affect- 
ing) the rest of the distribution mechanism. This facility is offered as a 
PostScript language debugging aid. 

See also: geteventlogger 

object integer setfileinputtoken - 

Used to define compressed tokens for communication efficiency, 
setfileinputtoken takes a specified object and a specified integer and associates 
them. They are then placed in the token list at the index location specified by the 
integer. 

bool setkeyboardtranslation - 

Kernel translation of the keyboard is turned on or off, as the argument is true or 
false. 

See also: keyboardtype 

NOTE Specijic to the Sun Operating System Interface; should eventually move into an 
environment dictionary. 
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setlinequaiity 



setmousetranslation 



setpath 



setprintermatch 



setrasteropcode 



n setlinequaiity - 

Sets the current desired line quality to n, which must be a number from 
Line quality controls the quality of lines rendered by the stroke primitive. 
Increasing values of line quality increase the quality of the rendered line, an< 
decrease performance. A value of 0 renders lines as fast as possible with the 
least attention paid to quality (the line thickness is ignored, lines are always 
single pixel wide). A value of 1 renders lines with the highest possible qual: 
they will be the correct width, and all endcaps and joins will be correct. Inte 
mediate values may give you different quality/performance tradeoffs. 

The default value for line quality is 1. If the value of line quality is not speci 
the lines drawn will be 1/72" wide, independent of your coordinate space. 

See also: currentlinequality 

boolean setmousetranslation - 

Instructs the underlying operating system to switch to the indicated mouse ti 
lation mode. The initial value is true . 

NOTE Specific to the Sun Operating System Interface; should eventually move into 
environment dictionary . 



path setpath - 

Sets the current path from the shape object path, 

boolean setprintermatch - 

Sets the current value of the printermatch flag in the graphics state to booU 
When printer matching is enabled text output to the display will be forced tc 
match exactly text output to a printer. The metrics used by the printer will 1 
imposed on the display fonts. This will usually cause displayed text to look 
bunched up and generally reduce readability. With printer matching disable 
readability will be maximized, but the character metrics for the display will 
correspond to the printer. 

See also: currentprintermatch 

num setrasteropcode - 

Sets the current rasterop combination function, which will be used in subse 
graphics operations. The values that setrasteropcode takes are the same as 
RasterOp function codes used by the Pixrect library, though they must be Cc 
lated: useful values are PIX_NOT (PIX_DST) = 5, PIX_SRC^PIX_DST 
PIX_SRC I PIX_DST = 14, etc. See the Pixrect Reference Manual for furl 
details. 

NOTE The RasterOp combination function exists only to support emulation of exis 

window systems. If you find yourself using it, you are probably making a m- 
and will have problems running your programs on a wide range of displays 
definition of rasterop is display-specific. Currently, the image and copM^e 
primitives do not use the rasteropcode. 
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setstate 



startkeyboardandmouse 



suspendprocess 



tagprint 



typedprint 



unblockinputqueue 



undef 



waitprocess 



See also: currentrasteropcode 



graphicsstate setstate - 

Sets the current graphics state from graphicsstate. 

See also: currentstate 

- startkeyboardandmouse - 

Initiate server processing of keyboard and mouse input. This is called once from 
early initialization code in init . ps, and should not be called again. 

process suspendprocess - 

Suspends the given process. 

See also: breakpoint, continueprocess 

n tagprint - 

Prints the integer n where -2'^<n <2'^ 

encoded as a tag on the current output stream. Tags are used to identify packets 
sent from the NeWS server to client programs. See Chapter 9, C Client Interface, 
for information on how the CPS input mechanism uses tags. 

0 typedprint - 

Print the object o in an encoded form on the current output stream. These objects 
can then be read by client programs using the facilities of CPS. The format in 
which objects are encoded is described in Chapter 14, Byte Stream Format. 

- unblockinputqueue - 

An input queue lock set by blockinputqueue is released. If this reduces the 
count of locks to 0, distribution of events from the input queue is resumed. If the 
count was already 0, a rangecheck error is raised. 

See also: blockinputqueue 

dictionary key undef - 

Removes the definition (if any) of key from the dictionary. 

process waitprocess value 

Waits until process completes, and returns the value that was on the top of its 
stack at the time that it exited. 

See also: fork 
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writecanvas 



writescreen 



file or String writecanvas - 

Either opens string as a file for writing, or if the argument is a file simpl^-^r 
to it. Creates a rasterfile which contains an image of the region outlined by tl 
current path in the current canvas. If the current path is empty, the whole car 
is written, writecanvas would be used to save an image in a file. 

See also: writescreen, eowritescreen , eowritecanvas 

file or String writescreen - 

Either opens string as a file for writing, or if the argument is a file simply wr 
to it. Creates a rasterfile which contains an image of the entire screen, wri- 
tescreen writes pixels from the screen, and it will include pixels from canva 
that overlap the current canvas. If the current path is empty, the whole canva 
written, writescreen could be used to do a conventional screen dump as fol 

framebuffer setcanvas (/tmp/snap) writescreen 

See also: writecanvas, eowritecanvas , eowritescreen 
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Omissions and Implementation Limits 



13.1. Operator Omissions The following PostScript language primitives were defined by Adobe, but have 

not yet been implemented in the NeWS POSTSCRIPT language interpreter. 

Table 13-1 Omitted POSTSCRIPT language primitives 



Primitive 


Note 


banddevice 


Printer specific. 


charpath 


Pseudo-implemented. 


copypage 


Pseudo-implemented. 


currentscreen 


Pseudo-implemented. 


currenttransfer 


Pseudo-implemented. 


echo 


Printer specific. 


executeonly 




framedevice 


Printer specific. 


invertmatrix 




noaccess 




nulldevice 


Printer specific. 


prompt 


Printer specific. 


renderbands 


Printer specific. 


resetfile 




restore 


Pseudo-implemented. 


reversepath 




save 


Pseudo-implemented. 


setscreen 


Pseudo-implemented. 


settransfer 


Pseudo-implemented. 


showpage 


Pseudo-implemented. 


start 


Replaced by user .ps/startup .ps initialization. 


translate 


Missing matrix argument version. 


usertime 





13.2. Imaging Omissions Two portions of the stencil/paint imaging model remain to be implemented: 

halftone screens and transfer functions. News pseudo-implements many operators 
specific to the POSTSCRIPT language printer interface with the statusdict diction- 
ary. The release file statusdict .ps contains these implementations. 
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13.3. Implementation 
Limits 

Table 13-2 Implementation Limits 



Quantity 


Limit 


Explanation 


integer 


32767 Integers are represented as 32 bits, 16 bits of the 
fraction. Integers are automatically converted to 
if they overflow. 


real 




Single-precision floating-point numbers are used 
Reals are represented as fractional integers if the; 
small enough, but the type determination operate 
describe them as real. 


array 


32767 Number of entries in an array. 


dictionary 


16384 Number of key/value pairs in a dictionary. 


string 


32767 Number of characters in a string. 


name 


32767 Number of characters in a name. 


file 




Number of open files (includes open client comr 
cation channels). The limit is 
getdtablesize ( ) -n, where n depends biitt 
ticular server but will be about four. 


userdict 


100 


Set by code in init . ps; easy to change. 


operand stack 


1500 


Maximum size of an operand stack. 


diet stack 




Expanded as required. 


exec stack 


100 


Maximum function/compound statement nesting 


gsave level 




Expanded as required. 


path 




Expanded as required. 


VM 




The server expands to use as much VM as the ur 
ing system permits. 


Interpreter level 




Not applicable. 


save level 




Not applicable. 
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13.4. Autobind When the POSTSCRIPT language interpreter encounters an executable name, the 

interpreter searches the dictionary stack from the top to the bottom until it finds a 
definition for this name. The execution time will therefore increase as the size of 
the dictionary stack increases. On the other hand, this method allows one to 
redefine the behavior of a name by defining it in a dictionary and placing this dic- 
tionary on the dictionary stack. 

The PostScript language provides an operator called bind that will circumvent 
this name lookup process, bind goes through a procedure and checks each exe- 
cutable name inside it. If a name resolves to an operator object in the context of 
the current dictionary stack, then bind alters the procedure by replacing the name 
with the operator object. This eliminates the time taken by name lookups when 
executing this procedure, but it removes the flexibility of being able to change a 
procedure’s behavior by redefining names before executing it. 

News implements an autobind mechanism which will cause every executable 
procedure to behave similarly to the way it would as if bind had been called on 
it. 

The following example illustrates the differences among the cases with no bind- 
ing, using bind, and using autobinding. 

^ - I ~ s 

^ ■:paper%v-psh;;.^ 

executive 

Welcome to NeWS version 1.1 

false setautobind 

/testl { 5 3 add == } def 

/test2 { 53 add == } bind def 

true setautobind 

/testZ.S (53 add == ) def 

false setautobind 

/add { sub } def 

/test3 {53 add == } bind def 

true setautobind 

/test4 { 5 3 add == } def 

' testl:.: 

■ 2 ■ 

test2 

. 8 .;: , 

test2 . 5 

' 8 - 

test3 

■ test4 

8 




In this example, the ‘test1 ’ procedure calls ‘add.’ Since ‘add’ was redefined to 



be ‘{ sub },’ ‘testl ’ really does a subtraction. The bind operator was used on 
procedure ‘test2,’ so the ‘add’ was not redefined as it was for ‘testl .’ Simi- 
larly, ‘test2.5’ behaves like ‘test2’ since autobinding was enabled, bind was 
run on ‘testS,’ but since ‘add’ now resolves to something other than an operator. 
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no binding takes place. The ‘test4’ procedure was defined with autobi^ 
on, but like ‘test3’, ‘add’ resolves to something other than an operator^s'5 1 
binding takes place. 

NOTE Autobinding is on by default. 

Autobinding can be turned on or off using the setautobind operator, which 
a boolean argument. You can use the currentautobind operator to get the 
current setting; it returns a boolean value. If you want to redefine the behav 
a name that is defined in systemdict, you should make sure that autobindinj 
off when the name is redefined and when procedures that use the new defini 
are defined. 




Revision A of 15 Janua 




14 

Byte Stream Format 

Byte Stream Format 157 

14.1. Encoding 157 

14.2. Object Tables 158 

14.3. Magic Numbers 159 

14.4. Examples 159 





14 

Byte Stream Format 



The information in this section is 
only of interest to those implement- 
ing the News protocol. Most C pro- 
grammers should use cPS, which 
deals with all of the protocol issues 
transparently. 



14.1. Encoding 



The communication path between NeWS and a client is a byte stream that contains 
PostScript programs. The basic encoding, which is compatible with 
PostScript language printers, is simply a stream of ASCII characters. News also 
supports a compressed binary encoding which may be freely intermixed with the 
ASCII encoding. The two encodings are differentiated based on the top bit of the 
eight-bit bytes in the stream. If the top bit is zero, then the byte is an ASCII char- 
acter. If it is one, then the byte is a compressed token. This differentiation is not 
applied within string constants or the parameter bytes of a compressed token. 

Each compressed token is a single byte with the top bit set. There may be 
parameter bytes following it and there may be a parameter encoded in the bottom 
bits of the code byte. In the following description of the various tokens, the 
values are referred to symbolically. The mapping between these names and 
numeric values is given at the end of this chapter. 

enc_int 

enc_int+(d<<2)+w;w*N 

0<w<3 and 0^<3; The next w-i-1 bytes form a signed integer taken from 
high order to low order. The bottom d bytes are after the binary point. This 
is used for encoding integers and fixed point numbers. 

enc_short_string 

enc_short_string+w,w*C 

0<w<15: The next w bytes are taken as a string. 

enc_string 

enc_string+w,w*L; l*C 

0<w<3: The next w+l bytes form an unsigned integer taken from high order 
to low order. Call this value / . The next / bytes are taken as a string. 



encsyscommon 

encjsyscommon +k 

0^ <32: Inside the News server there is table of POSTSCRIPT language 
objects. The enc_syscommon token causes the A:th table entry to be inserted 
in the input stream. Typically these names are primitive PostScript 
language operator objects. This table is a constant for all instances of 
PostScript language — the contents of the table are ‘well-known’ and 
static. This token allows common POSTSCRIPT language operators to be 
encoded as a single byte. 
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enc_syscommon2 

enc_syscommon2; k 

0<yk<255: This is essentially identical to enc_syscommon except that th 
index into the object table is k +32. This allows the less common 
PostScript language operators to be encoded as two bytes. 

enc_usercommon 

encjisercommon +k 

0<^<31; This is similar to enc_syscommon except that it provides user- 
definable tokens. E^ach communication channel to the server has an ass< 
ated PostScript language object table. The enc_usercommon token 
causes the A:th table entry to be inserted in the input stream. The table i 
dynamic; it is the responsibility of the client program to load objects int 
this table. The POSTSCRIPT language operator setlileinputtoken associ 
an object with a table slot for an input channel. 

enc_lusercommon 

encjusercommon +j\k 

0<; <3 and 0^<255; This is essentially identical to enc_usercommon ej 
that the index is 0 <'<8)+(^+32). 

enc_IEEEfloat 

encJEEEfloat ; 4*F 

The next four bytes, high order to low order, form an IEEE format float 
point number. 

enc_IEEEdouble 

enc_IEEEdouble ; 8*F 

The next eight bytes, high order to low order, form an IEEE double pre< 
floating-point number. 

14.2. Object Tables The enc_*common* tokens all interpolate values from object tables. The 

appearance of one of these tokens causes the appropriate object table entry t 
used as the value of the token. These tokens are typically a part of a POSTSt 
language stream that is to be executed and can be any kind of object. Usuali 
either executable keyword or operator objects are used. 

This has some subtle implications with scope rules. If the object is a keywo 
then its value will be looked up before being executed, just as an ASCII encc 
keyword would be. If it is an operator object, then the operator will be exec 
directly, with no name lookup. This improves performance, but it also bind; 
interpretation of the object table slot at the time that the slot is loaded. 

For example, if the executable keyword moveto were loaded into a slot, thei 
whenever that token was encountered moveto would be looked up and execi 
On the other hand, if the value of moveto were loaded into the slot, then wh^ 
ever that token was encountered the interpretation of moveto at the time the 
was loaded would be used. 
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14.3. Magic Numbers Here is the binding between token names and values; 

Table 14-1 TokenValues 



Value 


Span 


Symbolic Name 


0200 


16 


enc_int+(d«2)+w 


0220 


16 


enc__short_string4-w 


0240 


4 


enc_string 


0244 


1 


enc lEEEfloat 


0245 


1 


enc lEEEdouble 


0246 


1 


enc_syscommon2 


0247 


4 


enc_lusercommon 


0253 


5 


free 


0260 


32 


encsyscommon 


0320 


32 


enc_usercommon 


0360 


16 


free 



14.4. Examples The PostScript language fragment: 

10 300moveto 
(Hello world) show 

can be encoded simply as an ASCII text string: 

"10 300 movetoXn (Hello world) show " 

which would give a message that is 33 bytes long. The space following show is 
a delimiter; without it the tokens would run together. Binary tokens are self- 
delimiting. If the tokens were sent in compressed binary format then the mes- 
sage would be the following 19 bytes: 

Table 14-2 Meaning of Bytes in Encoding Example 

Byte Meaning 

0200 encoded integer, one byte long, no fractional bytes 
0012 the number 10 

0201 encoded integer, two bytes long, no fractional bytes 
0001 first byte of the number 300 

0054 second byte of the integer, 

(l«8)+054==0454==300 

0261 moveto — assuming that moveto is in slot one of 
the operator table, which it isn’t 

0233 (0220+11) start of an 11-character string 

0110 ‘H’ 

0145 ‘e’ 

0144 ‘d’ 

0262 show — assuming that show is in slot two of the 
operator table, which it isn’t 
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Supporting NeWS From Other 

Languages 



As it comes out of the box, the only language that is supported for NeWS clients 
(besides the raw POSTSCRIPT language) is C. The CPS preprocessor is primarily 
responsible for providing C support. What CPS and the libcps . a library pro- 
vide is a mechanism for contacting the server (ps_open_Post Script () ) 
and a mechanism for creating and sending messages to NeWS on that I/O chan- 
nel. 

15.1. Contacting the Server To contact the server from a UNIX environment you first need to get the environ- 
ment variable NEWSSERVER. This contains a string like 
3227656822.2000; paper. The first number is the 32-bit IP address of the 
server in host byte order. The second number is its IP port number. You need to 
create a socket and connect it to this IP address and port. Following the semi- 
colon in NEWSSERVER is the text name of the host on which the server is run- 
ning, which you can ignore. 

The setnewshost(l) command is a shell script that fabricates the appropriate 
string for NEWSSERVER. 

Once a connection has been established, all you need to do is write bytes down 
the stream as described in the Chapter 14, Byte Stream Format. Remember that 
you don't need to use the compressed binary tokens, they are merely an optimi- 
zation. It is perfectly satisfactory to send ASCII POSTSCRIPT language code with 
no compression. 

Eventually, a CPS-like program that is appropriate for the language should prob- 
ably be written. The basis for such a program would be the input and output 
facilities that CPS uses; the program could write routines that called them, or 
macros that expanded into invocations of them, or whatever other technique 
suited the host language. 

There is a C function called pprintf ( ) which is the mntime output work- 
horse behind CPS. It is invoked in a manner identical to fprint f ( ) (3s), with a 
format string that is interpreted in the same way. When values are output with 
o s or % d or any of the other formatting specifiers, they are output as 
compressed binary tokens. The rest of the format string is output as is; it may 



The psh(l) and say(l) programs provide these mechanisms to users who want simply to send 
PostScript programs to the server. 



15.2. Communication with 
the Server 
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contain compressed tokens or simple ASCII. 

Input from News to the client appears as bytes that can be read from the serve 
I/O stream. The format of these bytes is entirely up to the POSTSCRIPT langi 
code downloaded by the client into the server, so it may be as simple or as cc 
plex as you wish. There is a facility in News for writing objects back to the 
clients using the same compressed binary format as the client uses to send to 
server and a corresponding C procedure pscanf ( ) for interpreting these r 
sages. 
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16.1. Cursor Fonts 
A Standard Font 



Representation 




Font Tools 



This chapter describes how to create bitmap fonts and place them in the NeWS 
font library. It is like a cookbook; its level of detail is only good enough to 
create simple fonts such as cursor fonts and icon fonts, and to convert existing 
fonts into News’s format. It is not a complete description of the font format. The 
font utility programs described herein are all subject to change. With all these 
caveats aside, let us proceed. 

This section covers the creation of cursor fonts. 

News supplies the beginnings of a standard cursor font. The files involved are: 

$NEWSHOME/lib/NeWS/ cursor .ps 
$NEWSHOME/f onts/Cursor . f f am 
$NEWSHOME/f onts/Cursorl2 . f ont 

($NEWSHOME is the location of your NeWS installation, usually /usr/NeWS.) 
The intent is to build this font into a collection of well-done generic cursor 
images. As you develop such images you are encouraged to send them to Sun to 
be included in the standard cursor font. Some screening will be applied to weed 
out non-generic cursors. The advantages of using the standard cursor font 
involve a more uniform look between applications and greater resource sharing 
within the NeWS server. 

Cursors are normally implemented as bitmap fonts. The closest approximation 
to the requested font will be selected from the font library of bitmaps. 

Thus, cursor font shape descriptions are just bitmaps. The primary image is ren- 
dered in black over a white mask image. There is no such thing as an XOR cur- 
sor. 

If a user-defined font is used, the shape descriptions may be arbitrary 
PostScript language. Cursors may have dynamic color, image, transforma- 
tions, and shape. However, the cursor shape descriptions are called at the 
server’s discretion, not on every mouse motion. 
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Format The font utility mkiconf ont expects input in the format illustrated 

examples below. This happens to be the format generated by the SunV)^r A 
iconedit program, but can be generated in any manner. Here is an exam 
a cursor named pointer that is used for the root window in the default ini' 
file. Its image is that of a narrow arrow that points up and to the left. 

Form.at_version=l Width=16/. Height = 16, Depth=l, Valid_bit s_per_item-l 6 
^ XOrigin=0, YOrig:m=15 

0x0000, 0x4000, 0x6000, 0x7000, 0x7800, 0x7C00, 0x7E00, 0x7800, 

0x4C00, OxOCOO, 0x0600,0x0600, 0x0300,0x0300, 0x0180, 0x0000 

XOrigin and YOrigin indicate the origin of the character, which is the 
spot of the cursor. The values for XOrigin and YOrigin originate in t! 
bitmap’s lower left-hand corner with positive values extending up and to tht 
right. YOrigin is strange in that it starts from the last non-zero row of pi 
not the bottom of the bitmap. When using iconedit, XOrigin and 
YOrigin need to be entered by a separate text editor. 

Here is another example of a cursor named right jjrrow that is used by the r 
package supplied by the menu . ps file. Its image is that of an arrow that p 
right. 

Format_version=l ; Width=16, Height=16, Depth=l, Valid__bits_per_item=l 6 
^ XOrigin=17, YOrigin=6 

■k / 

0x0000, 0x0020, 0x0030, 0x0038, 0x0030, 0x7FFE, 0x7FFF, 0x7FFE, 
0x0030,0x0038,0x0030,0x0020,0x0000,0x0000,0x0000,0x0000 

Note that it is OK for the origin of the character to be off the edge of the bitr 

Cursors have a mask image and a primary image. Here is the mask for the 
pointer cursor. It is called pointer jnask. 

Format_version=l , Width=16, Height=16, ; Depth=l, Valid_bit s_per_item=l 6 
XOrigin=0, YOrig:_n=16 

OxCOOO, OxEOOO, OxFOOO, 0xF800 , OxFCOO , OxFEO 0 , OxFFOO , 0xFF80 , 

OxFEOO, OxDFOO, 0x9F00, 0x0F8 0 , 0x0F8 0 , 0x07C0 , 0x07C0 , 0x03C0 

Note that the mask image is used to outline the primary image and thus its c 
is offset by one from the primary image so as to superimpose the images 
correctly. This is typical of cursor masks. 

Generating a Font Here is the process for generating a simple font: 

1. Generate a collection of ASCII bitmap file pairs (see the Format section 
above). The convention is to call each cursor name . cursor and its n 
Azame_mask . cursor. Create a file containing these file names, each 
on a separate line. In this example, the file is called myfont.list — you 
name it whatever you want. The pair order should be primary file namt 
lowed by mask file name. 

2. Make an ASCII version of the font from the list of ASCII bitmap files^i^i: 
program mkiconf ont. The first argument to mkiconf ont i(7 yl 
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containing a list of file names. The second argument to mkiconf ont is 
the name of the output file prepended by a > and the intended name of the 
font family. 



x% mkiconf ont myfont . list MyFont>MyFontl2 . afb 

V ^ ) 

3. Turn the ASCII version of the font into a binary version using the program 
dumpf ont . The first argument should be a -d flag. The second argument 
is the directory in which the resulting . f b file should be placed (no spaces 
between the flag and argument). The third argument is the name of the file 
of the ASCII version of the font. The output file is named like the ASCII ver- 



sion but with a . f b suffix instead of a . afb suffix. 




r 

x% dumpf ont -d. MyFontl2.afb 

V 


J 


4. Build a font family file for the font using the program bldf amily. 
bldf amily will look in the current directory to find the font files. 




x% bldf amily -d. 




1 


J 



5. To reference the font symbolically, one can build a . ps file that contains a 
dictionary of character names for the font. Here is an example of the way to 
do this: 

#! /bin/sh 

egrep STARTCHAR [ ENCODING) " MyFont 12 . afb>myf ont . ps 
ed - myfont . ps<< ' EOF ' 
g/STARTCHAR/ j 

1, $s' STARTCHAR *) ENCODING ^)'/l /2 def' 
li 

/myfontdict 300 diet def 
myfontdict begin 
$a 
end 

% Usage: x y moveto /myfontname showmyfont 
/showmyfont { 

currentfont ( ) dup 0 myfontdict 5 index get put 
myfontfont setfont show setfont pop } def 
/myfont (MyFont) findfont 12 scalefont def 
w 

q 

EOT 



6. Copy the font and font family files to the font directory. 

x% cp MyFont.ff MyFontl2.fb $NEWSHOME/ fonts 



7. Copy the . ps to a well known place. 
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x% cp myfont.ps $NEWSHOME/lib/NeWS 



8. Use the . ps hie at the front of the font in your POSTSCRIPT program 

(NeWS/myfont.ps) run 
myfontdict begin 

myfont name name_mask setcanvascursor 
end 

In the PostScript language a font, like Times-Roman, is a scale-able obj 
font file containing a set of bitmaps is an instance of a POSTSCRIPT langua 
at some particular size and orientation. Because of the special requiremen 
the PostScript language, News has its own font hie format. A group of tl 
font hies, called family can be used to implement a POSTSCRIPT language 

There are two steps to create a POSTSCRIPT language font from a set of for 

1 . the font hies must first be converted into News format using dumpf or 

2, then a description of them as a family must be build using bldf ami: 

dumpf ont(l) will take a set of Adobe ASCII format or vfont(5) format hi 
convert them to NeWS format with file extension . fb . bldf amily(l) w 
a set of News fonts and build a font family hie with extension . f f . For a 
description of these programs and their options, see their manual pages. 

For example, say you have a set of vfont hies gacha . b . 7 , gach^^^/ 
gacha . b . 12, and gacha . b . 14; and you would like them to appear ii 
as the PostScript font Gacha-Bold. Call dumpf ont with this command 
— 

x% dumpfont -d$NEWSHOME/ fonts -S -n Gacha-Bold gach 

k 

dumpfont will convert the files named gacha .b . ^ into NeWS format, v 
them into the $NEWSHOME/font s directory (usually /usr/NeWS/fc 
calculate their size information by inspecting the bitmaps, and force the na 
Gacha-Bold. Then call bldf amily with this command line: 
— 

x% bldf amily -d$NEWS HOME /fonts 

k 

bldf amily will scan $NEWSHOME/f ont s for files named Gacha- 
Boldrt . fb. It will then build a font family file and write it to 
$NEWSHOME/ fonts/ Gacha-Bold . f f . Now you can send the POSTJ 
language code: 

(Gacha-Bold) findfont 

to the NeWS server to pick up the font family that you have built. You can 
PostScript language scalefont primitive to select from the different sizec 
maps. 



16.2. Building an Ordinary 
Font 
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Using News 



This chapter explains how to start up the NeWS server, and gives some very 
basic tips for getting started with NeWS and POSTSCRIPT language programming, 
including how to “personalize’' your server. 

Information on installing NeWS is in the NeWS Installation Guide. The examples 
in this section assume you have installed NeWS in /usr /NeWS or have mounted 
News over the NFS on /usr /NeWS; substitute its actual location if different. 

NOTE You can run NeWS from any directory, but it is easier to run psh programs (see 

below) if you have NeWS mounted on (or have symbolic links to) /usr /NeWS . 
Some of the demo programs cannot be run directly from a shell without 
modification if you do not have a /usr /NeWS/bin/psh, although they can 
be run from the menu. 

A.l. NeWS Environment The News server needs to know where its subtree has been installed, so that it can 

Variables find fonts, images, * . ps files, etc. Provide this information by: 

— .. 

paper% setenv NEWSHOME /usr/NeWS 

^ ^ 

The NeWS bin directory must be in the search path of the NeWS server process. It 
is also useful to put the demo directory into your path. So: 

paper% set path= ( /usr/NeWS/bin /usr /NeWS /demo $path ) 

V ) 

Running News on two displays is not 
supported. 



You can set these NeWS environment variables permanently in your . login file 
(for C shell users) or in your .profile file (for Bourne shell users). 



If your machine has multiple displays available, and you want NeWS to use a 
framebuffer other that /dev / fb as its default framebuffer, you can: 







A 




paper% setenv FRAMEBUFFER /dev/cgtwoO 




^ 




J 



or whatever device corresponds to the other framebuffer. 
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Which Server Binary? 



The Debugging Server Binary 



A.2, Starting up NeWS 

From outside suntools 



From within suntools using 
overview(l) 



Server Initialization 



A.3. SunViewl Binary 
Compatibility with 

News 



There are three versions of the NeWS server in $NEWSHOME/bin, 
news_server010 , news_serverO 10 . debug, and news_seb-v^: 
The file news__server(l) is a symbolic link to news_server010, whi 
the MC68010 (Sun-2) version of the server. This will run on Sun-2 and Su 
machines, but if you have a Sun-3 you should run news__server02 0 for 
increased performance. Read Various Versions of the NeWS Server in the Nl 
Installation Guide for more information on the different binaries (including 
4). 

The third version of the NeWS server found in $NEWSHOME/bin , 
news_server010 . debug has been compiled with full debugging enab 
Customers who have a reproducible crash are encouraged to reproduce it u^ 
this server. Run dbx on the resulting core file and submit the output from tl 
where and dump commands with the bug report. 

The News server news_server can be started in two ways. 




This sends diagnostic output to the shelltool or cmdtool from whic 
started the server^^. The News server takes over the screen, and when(^ 
SunViewl tools “underneath” will redisplay. 



Section A. 3, SunViewl Binary Compatibility with NeWS discusses some of t 
limitations on using NeWS and SunViewl tools together. 

In each case, the NeWS server starts by reading and executing the POSTScri 
language code found in the file init . ps. The standard init . ps file t 
others it executes define the desktop background, the root menus the sampl 
dow package, and other packages; see Chapter 4, Extensibility through 
POSTSCRIPT Language Files for more information on the contents of these 

Wdienever the server opens a file (including init . ps) it first tries to ope 
file in the current directory, and if this fails, it looks for it in 
$ {NEWSHOME } /lib. Usually the server is searching for BeVtS/filenam 

If you start up NeWS directly from the console it is possible to run unmodifi 
SunViewl ( or SunWindows-based) binaries within NeWS. Windows put u| 
SunViewl will appear to float over News, including even NeWS menus, but 
overlap other SunViewl based windows. One way of looking at this is tha 
NeWS, rather than the suntcols(l) program, manages the root window. 



NB: You must be sure that the FR.^.MEBUFFER environment variable used by the News senxr ma 
-d argument used by sunt oo i s. Both of tliese values default to /dev/ f b, so if one is changed, the 
must be also. 
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SunViewl windows appear to update the display simultaneously with News can- 
vases. SunViewl windows are surrounded by a white margin to avoid 
'‘glitches” when the cursor is moved between them and News canvases. 

NOTE Running SunViewl tools under NeWS when the latter is started up from within 
sunt oo Is is not supported. 

It is possible to use News and SunViewl applications simultaneously. However, 
you must make note of what version of the Sun OS you are running under. NeWS 
is not supported on versions of the Sun OS prior to 3.2. While running NeWS 
and a version of the OS with a release number equal to or greater than 3.2: 

□ Multiple SunViewl applications may run at the same time. 

□ SunViewl menus and prompts look fine, even over the NeWS window. How- 
ever, News menus appear to slide under SunViewl windows. 

□ SunViewl cross-hairs also work fine. 

□ Gfxsubwindow-based applications work fine. 

□ Very old versions (back to 1 . 1 ) of SunWindows-based applications work as 
well as they would under suntools. 

If you are determined to use NeWS on releases prior to 3.2, then you should add 
the following to your startup . ps file: 

UserProfile /UlModule /Default put 

If you make this modification, you will be able to type at psterm (the terminal 
emulator), but more complex actions such as making selections and typing to 
itemdemo will not work. 



Bugs in SunViewl/NeWS 
Coexistence 

Inconveniences 



This ability to run SunViewl programs from NeWS is handy, but not fully 

developed yet. As a result there are numerous bugs. 

□ A color SunViewl application needs the cursor over its window in order to 
see the application’s true colors. 

□ All of News repaints when a SunViewl window’s size or position changes. 

□ Annoying 

Window display lock broken after time limit exceeded \ 
by pid nnn 

messages appear on the console. You can adjust the display lock timeout by 
modifying the kernel with adb(l); see Section 7.5, Kernel Tuning Options, 
in the SunViewl System Programmer s Guide, 

□ If you run NeWS using overview(l) from within suntools(l) and you 
then run SunViewl applications inside NeWS, the colormap flashes when you 
move the cursor between News and the SunViewl applications. This is one 
reason why this configuration is not supported. 
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Screen Damage 



Input Mismatches 



News on the Sun-3/ 1 10 



You will sometimes see cursor “splotches.” This happens when you f Y 
SunViewl application over the cursor that is on News’s part of screen. 
also occur when moving from a SunViewl part of the screen to a NeWS part 
screen. To cure this, move any SunViewl window to cause repair and choc 
^Redisplay’ from the frame menu of the affected SunViewl application. 

The bottom scanlines of SunViewl windows get damaged by the NeWS serv 
a white line appears. 

SunViewl sets up the kb(4S) keyboard driver in the kernel to deliver encoc 
events, while NeWS uses an unencoded keyboard. The NeWS server resets th 
board state to SunView l encoding when the mouse moves into a SunViewl 
dow and when News exits, so you shouldn’t notice the difference. However 
you are debugging in NeWS and the NeWS server dies, NeWS doesn’t catch the 
nals that make it reset the keyboard state, and you may be left with the keyt 
producing random characters in SunViewl windows. The program kbd_m 
switches the keyboard between the different modes; you can r login to yc 
machine and type kbcijmode -e to reset to SunViewl mode, or add the 
lowing to your rootmenu SunViewl rootmenu file: 

"Reset Keyboard" kbd_inode -e 

Since the keyboard state is changed when you move the mouse between Ne^ 
and SunViewl, don t hold any keys down when you move the mouse from ' 
world to the other; the world you were in to begin with never sees the key i 
up, so it is confused about the keyboard’s state when you reenter it. 
leave you in secondary selection mode. You should be able to clear tlmby 
pressing the I Stop I key twice (usually I LI 1 1 in NeWS or SunViewl. 

If this does not reset the state of the function keys, you can r login to you 
machine and type clear_f unctions( 1) to get SunViewl’s selection m 
ism out of a constant secondary selection mode. 

On 3/110 models with the LC (cgf our) color monitor, if things go wrong 
the system seems to hang, the wrong plane group is probably being display 
To get out of this state, r login into your machine and type switcher 
— e- 1 to display the overlay plane or switcher ~e 0 to display the color p 
group. You can avoid a common cause of this problem if you create a sym 
link from /dev/ f b to / dev/cgf ourO . 
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A. 4. Learning NeWS The best way to learn News is to read the POSTSCRIPT language books, trying out 

sample POSTSCRIPT programs in News as you go (see Previewing POSTSCRIPT 
language Graphics below for more information). Then start examining and 
modifying the News demo programs and the server’s * . ps files. The following 
sections give further information on these topics. 

Putting A Message in a Window To simply display a message in a window, use the say(l) program. This has 

many options, but its default action is to put up a message in a window; for 
example 



paper% say -b” Text Using Say” Hello There 

\ ^ / 

will create a window, give it the frame header “Text Using Say”, and display 
“Hello There” in it. Since NeWS is a network service, you can easily put up a 
message on a remote machine with this command; see Section A. 4. 3, Connecting 
to Remote NSIVS Servers 

The psh Command The psh(l) command provides the easiest way to send POSTSCRIPT programs to 

the News server. There is a manual page for it in $NEWSHOME/man, which is 
also printed in the back of this manual. 

The psh command establishes a connection to the News server and sends it 
PostScript language fragments. If your program can live directly in the NeWS 
server, (i.e. it doesn’t have to communicate with a C client side), you can use 
psh to mn the code in the server. 

The News program you send to the server can create its own window and even 
define its own menu and input handling. The sample program described below in 
Section A.5, A Sample psh Program: test . psh uses this method, and it’s 
how many of the graphics demo programs work, such as bounce, colorcube, 
itemdemo, etc. 

psh need not create any window at all. For example, you might want to change 
the visual feedback that occurs when you move a window around the screen; this 
can be changed with the ‘User Interface => Window Management Style => Flip 
Drag’ menu item, and to do the same from the command line, the following code 
would suffice: 

echo ' /dragf rame? dragframe? not store' | psh 

Using Journalling When you select ‘Applications/ =>/ Journal’ from the root menu, a new pull-right 

menu is added to the root menu. 

From this you can start recording user input events, stop recording, play them 
back, or remove journalling. You can also bring up a control panel with buttons 
for controlling journalling, the speed of playback, auto-repeat, the journalling file 
to use, etc. See Ch.4, Extensibility through POSTSCRIPT language Files for more 
detailed information. 



Running POSTSCRIPT language 
Programs 
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Previewing POSTSCRIPT 
language Graphics 



You can use psh to directly preview graphics by creating your own wi^^\ 
defining a PaintClient procedure for it that includes your POSTSCRIPT ferig 
code. PaintClient is called whenever the window is resized or damaged (st 
Section 7.4, Window Methods), 

However, you must be aware of some differences between psh and a 
PostScript language printer. Firstly, various printer-related commands su 
showpage are meaningless or pseudo-implemented in the News window en^ 
ment. Secondly, the default Sun LaserWriter coordinate scheme is one unit 
one point on the paper (a point is 1/72 of an inch), so that a U.S. letter-sizec 
goes from (0,0) to (612,792), whereas the window canvas is scaled in pixeh 
begin with. 

The program psview(T) implements a page previewer that gets around the 
problem by including some additional code to scale the coordinate space to 
match the canvas. 



Talking Directly to the Server The News server is a POSTSCRIPT language interpreter, and you can use it ii 

tively to program and debug. Usually you use the psh command to conm 
the server, then run the executive command to start an executive, an interac 
session with the server. 

/ ^ 

paper% psh 

executive 

Welcome to NeWS Version 1.1 
V ^ ^ 



A Sample Session Once running an executive, you can type in any POSTSCRIPT language com 

mands you want. The following miscellany perform some arithmetic, defir 
function called ‘centigrade’, and find out some stuff about the NeWS server 
further commands print some words and draw arcs of various styles on the 
screen. 



(see Chapter 8, Debugging). 
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340 1024 mul = 

348160 

/centigrade { 

32 sub 5 mul 9 div 
} def 

70 centigrade = 

21.1111 

32 centigrade = 

0 

currentcanvas = 

canvas {width ^ height ^ root) 

100 100 moveto 

/Times-Italic findfont 24 scalefont setfont 
(Hello world!) show 

newpath 

150 200 50 90 0 arc 
stroke 

1 setlinequality 1 setlinejoin 30 setlinewidth 

300 200 50 90 0 arc 

stroke 



Connecting to Remote News 
Servers 



The environment variable NEWS SERVER determines which server client pro- 
grams will access; by default they access the local host. There is a utility pro- 
gram, setnewshost (1) which outputs the correct setting of the NEWS SERVER 
variable for a given remote host. You can also craft the value of NEWSSERVER 
yourself using the information about its format in Section \5.\ , Contacting the 
Serve! . 

After you define NEWSSERVER, say and other NeWS client programs will 
display their output on remote Jiost, and psh with no arguments will connect to 
remote Jiost allowing you to run an interactive programming session on a remote 
machine. For example, to display a message on machine neighbor: 

paper % setenv NEWSSERVER 'setnewshost neighbor' 
paper% say -bLunch -c -w -100,200 "Come have lunch" & 

V J 

neighbor has to have allowed a NeV/s connection from paper for this all to 
work. See Chapter W.NeWS Type Extensions, section 1 1.9, NeWS Security for 
more information. 

More commonly, you can use the network aspect of NeWS in reverse to run NeWS 
applications on fast remote machines while you interact with them on your own 
workstation. For example, you could use the on(l) remote execution service 




News is a network-based window system, so you can connect to remote NeWS 
servers and display output on them (remember, the server runs on the machine 
with the display and keyboard, providing them as a resource for the client pro- 
gram). 
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(which preserves environment variables like NEWS SERVER) from with^”^< 
psterm(l) terminal emulator (which explicitly sets NEWS SERVER to thei^ 
server it is running on) to run the roundclock program to determine the t 
on a remote machine. 

A.5. A Sample psh The following program is a script that creates its own window and displays « 

Program: test . psh of several graphic patterns, depending on the menu item selected. The soun 

in $NEWSHOME/clientsrc/client /test .psh. 

The sample program uses psh(l) to connect to the News server. The first li: 

# ! /usr/NeWS/bin/psh 

means that if the file is executable, it will be run by /usr /NeWS/bin/ps 
you do not have News mounted on /usr/NeWS, you have several choices: 

1. Change the first line to reflect the location of psh on your host. 

2. Type 

psh /test , psh 

to run the script. 

3. Modify the script to be: 

#! /bin/sh 
psh « \EOF 
... current script 
EOF 

(the «\EOF on thie command line is a shell convention indicating that 
entire file up to the string EOF should be sent to the standard input of ] 
the backslash tells the shell not to perform metacharacter substitution o 
input, which is useful if the POSTSCRIPT language code contains shell r 
characters). 

The patterns are drawn by the procedures ‘Lines,’ ‘Circles,’ ‘Rects’ and ‘1 
these are defined first. Then a ‘main’ procedure is defined: this creates the ^ 
dow and a menu for it using procedures from the LiteWindow and LiteMenu 
classes, which handle event processing (putting up the menu when the mem 
mouse button is pressed, calling the ‘Draw’ procedure to repaint, etc.), ‘me 
called to begin the program. 

The procedure ‘Draw’ is set to one of the graphics procedures to begin with 
is reset when one of the procedures is selected from the menu. Note that if ‘ 
is selected, ‘Draw’ is set to all four graphics procedures, so each is rapidly c 
in turn. The window’s PaintClient procedure is set to ‘Draw’, so wheneve: 
window is damaged or redisplayed, the current graphics procedure is called. 

#! /usr/NeWS/bin/psh 

% define each of the four possible drawing routines 
% lines', ‘Circles', ‘Reefs', and ‘Text'. 

% Note the use (9/ pause in each drawing routine. This allows other programs 
% to run simultaneously. 



When reading PostScript 
language source, it’s often eas est 
to start from the bottom and work 
backwards, since subprocedures 
are usually defined before the main 
body of the code 
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/Lines { 

gsave % It’ s a good idea to do a gsave... 

% grestore around graphics operations. 

1 fillcanvas clippath pathbbox scale translate 

.1 .1 1 {0 0 moveto dup 1 lineto 0 0 moveto 1 exch lineto pause} for 

0 setgray stroke 
grestore 

} def 

/Circles { 
gsave 

1 fillcanvas clippath pathbbox scale translate 

0.1.4 (dup 0 0 11 insetrect ovalpath 2 mul setgray fill pause) for 
grestore 
}def 
/Rects { 
gsave 

1 fillcanvas clippath pathbbox scale translate 

0 .1 .4 {dup 0 0 11 insetrect rectpath 2 mul setgray fill pause) for 
grestore 

} def 
/Text { 
gsave 

1 fillcanvas 0 setgray 

/Fonts [ % This is an array of font names 

(Times-Roman) (Times-Bold) (Times-ltalic) 

(Helvetica) (Helvetica-Bold) (Helvetica-Oblique) 

(Courier) (Courier-Bold) (Courier-Oblique) 

(Symbol) (Boston) (Cyrillic) 

]def 

/PointSize 24 def 
/y 1 0 def 
Fonts { 



dup findfont PointSize scalefont setfont 10 y moveto 
1 0 {dup show 1 5 0 rmoveto) repeat pop 
/y y PointSize 1.1 mul add def 
pause 
} forall 
grestore 
} def 

/Draw {Text} def % Initial drawing procedure w ‘Text’ 

% ‘T ext’ has the window draw me so that I inherit certain 
% side effects, such as forking the FaintClient procedure 
% and setting the graphics state. 

/CallDraw {/paintclient win send) def 

/main { 

/win framebuffer /new DefaultWindow send def 

{ 

/Paintclient (Draw} def 



% Create a window 

% Modify the window. There are default 
% procedures for each of these. 

% /Paintclient will be called 
% whenever my image needs to be 



% The forall operator below performs 
% this procedure for each font in the 
% 'Fonts' array 
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/FrameLabel (Demos!) def 
/Iconimage /heilo__woiid def 
/ClientMenu [ 

(Lines) {/Draw {Lines} store CallDraw} 

(Ovals) {/Draw {Circles} store CallDraw} 

(Rectangles) {/Draw {Rects} store CallDraw} 

(Text) {/Draw {Text} store CallDraw} 

(All!) {/Draw {Lines Circles Rects Text} store CallDraw} 
] /new DefaultMenu send def 

} win send 



/reshapefromuserwin send 

% Do initialization. Then have my window mapped (made visible) 
% which will cause the paint procedure to be called. 

/map win send 

}def 

main 



% repaired or redisplayed. 

% Make the menu and give it to the 
% window event manager to handle. 



% /new is one of the well-known 
% methods in the menu class. 

% Sending a procedure to an object 
% will cause it to be executed in 
% the object' s context. 

% Ask the user to shape the window. 



% Map (&. activate) the window. 

% Damage will cause PaintCHent 
% to be called. 

% start everything going 
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A. 6. Dictionaries and the When the News server starts up, it ams a file called init . ps. init .ps in turn 
Server loads several PostScript language files that implement a variety of packages; 

see Section 4.2, File Organization for a summary of their organization and con- 
tents. These are all ASCII POSTSCRIPT language files that you can and should 
look at. 

Modifying the XeVVS Server It is possible to modify these files, or make copies of them and put them in the 

directory from which you start the NeWS server. Thus you can override the 
default init . ps (or any of the files it loads) by putting a private version of the 
file in the directory from which you start the server; For example, if you create a 
News directory in the directory from which you start news_server, and put 
your own init . ps file in that, the server would run your version instead. 
However, it is better to override the default procedures specified in these start up 
files by creating your own star tup , ps and user . ps files. These aren’t 
supplied with NeWS; users who want to change the server’s behavior are 
encouraged to create their own. 

You should place startup . ps and user . ps in your home directory or the 
directory from which you start News, {not the directory the NeWS server itself 
resides in), init . ps first looks in the directory the NeWS server was started 
from, then in your home directory (given by the HOME environment variable) 
when it tries to load startup . ps and user .ps. 

startup . ps Before it loads anything else, the default init . ps file looks to see if a file 

called startup.ps exists. If it does, it executes the POSTSCRIPT language 
commands therein. These commands would typically be to set flags, such as ver- 
bose?, or to install a special PaintRoot procedure that is used during startup. 

NOTE Since the system's own FOSTSCRfPT language files have not been read in when 
startup . ps is loaded, you cannot use any of the routines described in 
Chapter 4, Extensibility through POSTSCRIPT Language Files, or the packages 
(windows, cursors, etc.) they implement. 

Then init . ps loads a standard set of POSTSCRIPT language files that define 
the classes, packages and user interface for News. 

user.ps Next, init . ps looks to see if a file called user . ps exists. If it does, it exe- 

cutes that too. user . ps is a convenient place for you to override default set- 
tings in the standard init . ps, and to define useful procedures for your own 
use. 

Then the server starts listening for connections and for mouse and keyboard 
events. 



Notes on Modifications When client programs are run and first start defining procedures, they make 

entries in a per-process user dictionary. However, the user . ps file adds pro- 
cedures to the system dictionary, which has a finite amount of room available. 
More importantly, the system dictionary is shared by all processes, so you do not 
want to clutter it up with lots of definitions because this will increase the risk of 
name clashes. 
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If you are going to define lots of new functions, it’s best to create youii^ 
tionary from within user . ps as follows ; 

% Define my VDI emulation routines 
systemdict /myVDIdict known not { 

systemdict /myVDIdict 50 diet put % size to however many entries are in . 
myVDIdict begin 
/VDIrange 34200 def 
etc. 
end 
}if 

This checks to see if ‘VDIdict’ is already defined in the system dictionary; 
isn’t, it creates its own dictionary, only adding one entry to the system diet 
ary. You can access your own dictionary of extensions as follows: 

myVDIdict begin 
VDIrange 4 mul 

etc. 

end 

(Or you can use the get, store and put primitives.) 

Here are some examples of modifications you can make in user . ps. 

Modifying Your “Root” Menu The following code in user . ps will add a new pullright menu, myStuff, t 

root menu. This in turn has two items, another pullright menu called myW 
and a menu item that mns the UNIX program my go. 

/projectmenu [ 

(test program) { (work.tst) forkunlx } 

] /new DefaultMenu send def 

/mymenu [ 

(myWork =>) projectmenu 
(my Go game) { (mygo) forkunix } 

] /new DefaultMenu send def 

0 (myStuff =>) mymenu /insertitem rootmenu send 



Saving Keystrokes 



If you often connect to the server directly, you can redefine commonly use 
mands to save typing. 



You should not use these shortened 
names in client programs since the 
definitions will not exist on other 
machines. 



The following code added to your user . ps redefines several common cc 
mands to save keystrokes. 



■Asun 

Xr microsystems 



Revision A of 15 Janu 




Appendix A — Using News 185 



Changing Defaults 



% Some aliases 
/ps {pstack} def 
/cds {countdictstack =} def 
/fb framebuffer def 
% Debugger 

/dbe {dbgbreakenter} def 
/dbx {dbgbreakexit} def 
/dc {dbgcontinue} def 
/dib {dbglistbreaks} def 
/dwb {dbgwherebreak} def 

(keystroke savers ps, cds, fb, dbe, dbx, dc, dIb and dwb defined\n) print 

The following code added to your user . ps will load the optional debug pack- 
age and change item dragging behavior if running on a color display so that only 
a wire frame of the window is dragged, not the entire window which requires 
more memory to perform this adequately. 

(Loading debug. ps\n) print (debug.ps) run 
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B.3. Class Labeleditem 

B.4. Subclasses of Labeleditem 

B.5. Labeleditem Subclass Details 




B 



Class Liteltem 



This chapter presents a class-based items package, called ’’Liteltem.” Items are 
simple, graphical input controls, like SunView's panel items. The item package 
is a further demonstration of the use of classes and packages besides the window 
and menu packages described in Chapter 7, Window and Menu Packages. The 
item package is only used by the itemdemo demo program. The POSTSCRIPT 
language code for the items package is in the file liteitem.ps in 
$NEWSHOME/lib/NeWS. 

CAUTION This package is included for demonstration purposes only. No support for it 
in the future is implied. 

The item package currently implements the base class, Item (which is useless by 
itself), the subclass Labeleditem (which also is useless), and several practical 
subclasses of Labeleditem (which are useful). 

B.l. Class Item A common need in interactive systems is a simple, user-definable, graphic, 

interactive, inpui/output object. Examples are buttons, sliders, scrollbars, dials, 
text fields, message areas, and the like. The class Item defines a skeleton for 
such an object. 

An item has these major components: 

□ A canvas that depicts the item and is the target of the item’s input. 

□ A set of procedures that paint the canvas and handle activation and tracking 
events. 

□ A current value and a procedure that notifies the client when that value 
changes due to action of the tracking procedures. 

□ Methods for creating, moving and painting the item, and for returning the 
item’s location and bounding box. 

There are two utilities for items that reside outside of the class itself: forkitems 
and paintitems: 
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forkitems items forkltems process 

Takes an array or dictionary of items and launches a process looking foT-afi 
activation event (generally a mouse down event) for each of the items. Wht 
this occurs, a second event manager is forked that looks for events this parti 
item is interested in. 

paintitems items paintitems - 

Sends the /paint message to each of the items in an array or dictionary of it 

Let’s take a look at the definition of class Item: 

/Item Object [ 

% instance variables 



/ItemWidth 


% item' s width. 


/ItemHeight 


% ...and height, 


/ItemParent 


% ...and parent canvas (from new) 


/ItemCanvas 


% the canvas we created for the item 


/ItemValue 


% the canvas’ current value 


/ItemlnitialValue 


% the value it started out with 


/ItemPaintedVaiue 


% the value it currently shows 


/Startinterest 


% the interest which activates the item 


/Item Interests 


% interests used to track item 


/ItemEventMgr 


% ...the tracking process 


/NotifyUser 


% the user’s notify proc 


] classbegin 

% default variables 


/ItemFont DefauItFont def 


% the item’ s font 


/ItemTextColor 0 0 0 rgbcoior def 


% ...Sc. text color 


/ItemBorderColor ItemTextColor def 


% ...Sl border color 


/ItemFillCoIor 1 1 1 rgbcoior def 


% ...Sc. background color 


% class variables: mainly the std client procs 


/Paintitem nullproc def 


% the core of the /paint method 


/ClientDown nullproc def 


% procedures installed in 


/ClientDrag nullproc def 


% the acti vated ( tracking ) 


/ClientEnter nullproc def 


% process 


/ClientExit nullproc def 
/ClientKeys nullproc def 
/ClientUp nullproc def 


/StopOnUp? true def 


% deactivate on up event? 


% methods 


/new 


% parentcanvas width height => insi 


/makecanvas 


% - => - 


/makeinterests 


% — => — 


/move 


% X y => - (Moves item to xy) 


/moveinteractive 


% item’s backgroundcolor => ~ 


/paint 


% (interactively moves the item) 
% - => - ([Re] paints item) 


/location 


% - => X y 


/bbox 


% - => X y w h 


classend def 


The canvas and its “looks” are defined by: 



ItemWidth, ItemHeight, ItemParent, ItemCanvas, ItemFont, Item 
TextColor, ItemBorderColor, ItemFillCoIor 
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The parent canvas, height, and width are specified by the /new method. The oth- 
ers are initialized by the class and may be changed by the programmer or user. 

The set of procedures for painting the canvas and handling activation and track- 
ing events are: 

Paintitem, Startinterest, Iteminterests, ItemEventMgr ClientDown, 
ClientDrag, ClientEnter, ClientExit, ClientKeys, ClientUp, StopOnUp? 

The Paintitem procedure is called by the /paintitem method, after it sets the 
canvas and does some minor bookkeeping. Startinterest is an event used by the 
forkitems utility to determine when to fork a second event manager, 
ItemEventMgr, to perform ‘ ‘tracking’ ’ of the item. Startinterest defaults to a 
mouse down event and generally is not overridden. Iteminterests is a dictionary 
of events used to track the item. It defaults to a set of events determined by 
which of the ‘ClientFoo’ procedures have been overridden to be non-null. It is 
made by the /makeinterests method, which is generally invoked by the /move 
method as part of the item’s deferred initialization. Clients are free to call Item- 
Interests themselves, however, if the need arises. ItemEventMgr is the tracking 
process and is null when tracking is not being performed. StopOnUp? is a 
boolean (default = true) that tells the tracking process whether to terminate on an 
up mouse event. (At present, only text items do not terminate on an up mouse 
event.) 

The current value and notification procedures use: 

ItemValue, ItemlnitialValue, ItemPaintedValue, NotifyUser 

ItemValue is the current value of the item. For example, it might be the string 
currently in a type-in item or true/false for a button item (indicating whether the 
button is currently on or off). ItemlnitialValue is set to ItemValue when the 
item is activated for tracking. ItemPaintedValue is set to the value currently 
painted. These last two values are used to maintain a simple state machine by 
class implementations. NotifyUser is a procedure used to alert the client of 
changes in state. 

B.2. Two Sample Items These two subclasses of Item implement a simple toggle button and a simple 

slider. They both override the /new method, adding the initial ItemValue and 
the NotifyUser procedure to the argument list. Notice the way overriding is 
done: 

/new super send begin 

currentdict 

end 

This is a standard POSTSCRIPT language programming style. 

‘SampleToggle’ provides tracking by implementing the client ‘Down’, ‘Up’, 
‘Enter’, and ‘Exit’ procedures. ItemValue is treated as a boolean, with true 
meaning “on”. ‘Down’ and ‘Enter’ simply assign not ItemlnitialValue to 
ItemValue, while ‘Exit’ resets it to ItemlnitialValue. ‘Up’ simply calls the 
‘notify’ procedure if the state has changed. ‘SampleToggle’ adds no instance or 
class variables. 
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Here are two toggles, one on and the other off, and the implementatioriii^ Jl 
class ‘SampleToggle’: 
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Figure B-1 Two Instances of Class 'SampleToggle' 

/SampieToggle Item [] 
ciassbegin 

/new { % initialvalue notifyproc parent width height =: 

/new super send begin 
/NotifyUser exch cvx del 
/itemValue exch def 
currentdict 
end 
} def 

/Paintitem { 

ItemValue 
{0 fillcanvas} 

(1 fillcanvas 0 strokecanvas} ifelse 

}def 

/ClientDown {ItemlnitialValue not SetToggleValue} def 
/ClientUp {ItemValue ItemlnitialValue ne {NotifyUser} if} def 
/ClientEnter {ClientDown} def 
/ClientExit {ItemlnitialValue SetToggleValue} def 

/SetToggleValue { % value => - (set value &. paint toggle) 

/ItemValue exch store 
/paint self send 
}def 

classend def 

The ‘SampleSlider’ provides tracking by implementing the client ‘Down 
‘Up’, and ‘Drag’ procedures. The ‘Down’ and ‘Drag’ procedures are ider 
simply projecting the current x coordinate of the mouse onto the slider. 




Revision A of 15 Janu 




Appendix B — Class Liteltem 193 



Here is a slider and its implementation: 




Figure B*2 An Instance of Class 'SampleSlideF 

/SampleSlider Item [/SiiderX /SliderY /SliderWidth /SliderHeight] 
dassbegin 

/new ( % initialvalue notifyproc parent width height => item 

/new super send begin 

/NotifyUser exch cvx def /ItemVaiue exch def 
/SiiderX ItemHeight 2 div 1 sub def 
/SliderY ItemHeight 2 div def 
/SliderWidth ItemWidth ItemHeight sub def 

/SliderHeight 2 def 

currentdict 
end 
}def 

/Paintitem { 

ItemCanvas setcanvas 1 fillcanvas 0 strokecanvas 
SiiderX SliderY SliderWidth SliderHeight rectpath fill 
ItemVaiue 0 PaintSliderValue 
} def 

/ClientDown { 

SetSliderValue 

ItemVaiue ItemPaintedValue ne { 

ItemPaintedValue 1 PaintSliderValue 
ItemVaiue 0 PaintSliderValue 

}if 

} def 

/ClientUp {ItemVaiue IteminitialValue ne (NotifyUser) if) def 
/ClientDrag {ClientDown} def 
/PaintSliderValue { % value gray => - 

setgray 

SiiderX add SliderY 5 sub 4 4 rectpath fill 
/ItemPaintedValue ItemVaiue store 
}def 

/SetSliderValue { 

/ItemVaiue 

CurrentEvent geteventlocation pop SiiderX sub 
0 max SliderWidth min store 

}def 

classend def 
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Sample Items Test Program Now we’ll play with these procedures using a simple test program. 

procedure simply prints the value of the item using the printf utility. WcN 
building a canvas and painting it with Mtembackground.’ Then we make i 
items, a button and a slider, putting them in a dictionary called Items.’ W 
paint them and fork an activation event manager. 

This is usually all you need; we throw in an extra event manager, 'p1 that 
the middle mouse button to move the items interactively with the ’Slide iter 
procedure. It then prints out the new location. (This is a poor man’s item e 
that often is useful.) 



Here’s what the test looks like, and its implementation: 




Figure B-3 The Sample Test Program 
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/ItemSampleTest { 

/notify {Item Value (ItemValue: % \n) printf} def 

/itembackground .75 def 

/can framebuffer 200 200 createcanvas def 

can setcanvas 200 100 movecanvas currentcanvas mapcanvas 

itembackground fillcanvas 0 strokecanvas 

/items 1 0 diet dup begin 
/sampletoggle 

false /notify can 30 30 /new SampleToggle send def 
1 0 30 /move sampletoggle send 
/sampleslider 

20 /notify can 1 80 20 /new SampleSlider send def 
1 0 70 /move sampleslider send 
end def 

items paintitems /p items forkitems def 

/slideitem { % - (event) => - 

/item CurrentEvent /action get def 
items itembackground /moveinteractive item send 
(New bbox: % % % % \n) [/bbox item send] printf 
} def 
/pi [ 

items { % key item 

/item exch def pop % ~ 

MiddleMouseButton {slideitem} % but proc 

1 diet dup DownTransition item put % but proc diet 

item /ItemCanvas get eventmgrinterest 
} forall 

] forkeventmgr def 
} def 



After pushing the toggle and sliding the slider, we have: 



Directory: /usr/owen/ps/server 



ij::; ^ 

iji: b1gmac% 

Starting server 

iji: ^ Initialization files loaded! 

Starting root eventmgr 
i':;': Hi there! 

Ijx ItemSarnpleTestJ 
ItemValue; true 




Figure B-4 Use of the Sample Test Program 
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.A.fter we push the middle button on the slider and move it, we get; 



Di rectory: /usr/owen/ps/server 



^1 n led on /usr/owen/Log 



b1 gmac% 

Starting server 
Initialization files loaded* 
Starting root eventrngr 
HI there! 

ItemSarnpl eTest 
IternValue: true 

IternValue; 104 
New bbo?<:: 10 169 180 20 




Figure B-5 Use of the Sample Test Program — Moving the Slider 

What to notice here is the simplicity and power both of the program and sai 
items, and of the News programming environment. The implementation of 
items and test program, and the testing of them both in the interpretive NeW 
environment takes very little time. 

B.3. Class Labeleditem Most items are more elaborate than the preceding examples. Class La&elet 

implements a more common item; one that has a label-object pair, and an 
optional frame. The (abbreviated) class definition is: 
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/Labeleditem Item 




dictbegin 


% instance variables 




/ItemObject 


nullstring def 


% The item’s ‘'object’' 


/ObjectX 


0 def 


% and bounding rect: 


/ObjectY 


0 def 




/ObjectWidth 


Odef 




/ObjectHeight 0 def 




/ItemLabel 


nullstring def 


% The item’s “label” 


/LabeiX 


0 def 


% and bounding rect: 


/LabelY 


0 def 




/LabelWidth 


Odef 




/LabelHeight 


0 def 




/ItemBorder 


2 def 


% Extra space around the item 


/ObjectLoc 


null def 


% Label-Object position 


/ItemGap 


5 def 


% Distance between object &. label 


/ItemFrame 


Odef 


% Draw frame if not zero 


/ItemRadius 


Odef 


% Radius of frame 


dictend 

ciassbegin 


% default variables 





/ItemLabelFont Item /ItemFont get def 
% class variable: over-ride of Paint Item 

/Paintitem % - => - 

% methods: over-ride new 



/new % label obj loc notify parent width height => instance 

% utilities used to manipulate label-object pair 

/LabelSize %-=> width height 

/ShowLabel % _ => _ 

/ShowObject % - => - 

/EraseObject % - => - 

/AdjustItemSize % - => - 

/CalcObj&LabeIXY % ~ => - 

classend def 



The label and object and their item-relative bounding rectangles are defined by: 

ItemLabel, LabelX, LabelY, LabelWidth, LabelHeight, ItemObject, 
ObjectX, Object Y, ObjectWidth, ObjectHeight 



The ItemLabel and ItemObject are either a string, an icon keyword, or a pro- 
cedure keyword. If it is a procedure, it takes a boolean as an argument: true 
causes it to draw itself; false causes it to return its width and height. The Item- 
LabelFont is bound to the label, the ItemFont is bound to the object. 

The item’s layout metrics are defined by: 

ItemBorder, ObjectLoc, ItemGap, ItemFrame, ItemRadius 

ItemBorder is the space between the item bounding box and its label-object 
pair. ObjectLoc is the position of the object relative to the label. It may be any 
of /Right, /Left, /Top, /Bottom. ItemGap is the space between the label-object 
pair. ItemFrame is the size of the frame to draw around the item. It should be 
no greater than ItemBorder. ItemRadius is the curvature of the item’s border. 
Zero represents a rectangular shape; a number between 0 and .5 represents a 
rounded rectangle whose radius is that fraction of the shortest edge; and any 
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Other number is used as the absolute curvature of the rounded rectanelf^ 

The two overrides are the /new method and the /Paintitem procedure calk 
rhe /paint method. Note that /new adds label, obj, ioc, and notify to the a 
ments of its superclass. These are bound to ItemLabel, ItemObject, 
ObJectLoc, and NotifyUser, respectively. 

Class Labeieditem contains a few utilities that are used by its subclasses: 

LabelSize, ShowLabel, ShowObject, EraseObject, AdjustItemSize 
CalcObj&LabelXY 

LabelSize returns the height and width of the label. ShowLabel and Shov 
ject paint the label and object in the item’s canvas: EraseObject erases tht 
object. AdjustItemSize and CalcObj&LabelXY are two layout utilities. 
AdjustItemSize is used to insure the item is large enough for its label-obje 
while CalcObj&LabelXY is used to adjust the label-object pair’s relative 
tions. Note that CalcObj&LabelXY adds the initial values of the label an 
object locations, which default to 0, to the calculated locations, thereby prc 
for slight adjustments by the programmer. 

B.4. Subclasses of This section presents several practical subclasses of Class Labeieditem, s 

Labeieditem ing how they are used by client programs. There are further examples of ii 

usage in the itemdemo program provided in the standard release. The ii 
mentation of these classes is included in the item . ps file that implemen 
Class Item and Class Labeieditem. Programmers wanting to implernent 
own items should look at these implementations; they are generally l^^h 
page of PostScript language. 

The subclasses are: 

□ Buttonitem: provides a simple activationyconfirmation item 

□ Cycleltem: provides check boxes and choices 

□ Sliderltem: provides a continuous range of values 

□ Textitem: provides a type-in area 

□ Messageltem: provides an output area 

□ Arrayltem: provides an array of choices 
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This window contains one of each of these items; 







Izsrns 

— , 










0^ Cycleltem 




I^Qtwo @ 


Messageltem 
ItemVdue Foo 








Textltem: Foo 






Four Q Six 

Arrayltem 








ctvTf iatvk ■ 


0 














* 






















J 



Figure B -6 Subclasses of Laheledltems 
Things to notice: 

□ All items except button items have the following arguments: 

label object location notifyproc parentcanvas width height 

Buttons have no object; thus leave out object and location. Cycle and array 
items have multiple objects in an array. 

□ All four object locations are visible in the sample: 

• The text and slider items use /Right 

• The cycle item uses /Left 

• The message item uses /Top 

• The array item uses /Bottom 

□ The width and height parameters are hints only; the AdJustItemSize pro- 
cedure will increase these if necessary. The minimal size will be enough to 
contain the label-object pair separated by ItemGap with a border of Item- 
Border. The message item in the example below uses this by using a 0,0 
size for the canvas but a large empty string as the initial value of the mes- 
sage. 

□ The values calculated by CalcObJ&LabelXY 

LabeIX LabelY ObjectX ObjectY 

can be adjusted by assigning initial values to any of them. This is used in 
the check box example above: 

/cycle (Cycleltem) [/panel_check_off /panel_check_on] 

/Left /notify can 0 0 /new Cycleltem send 
dup /LabelY -4 put 10 70 /move 3 index send def 

□ The label or object can generally be either a string, an icon name, or a pro- 
cedure. The procedure takes a boolean which indicates whether to draw the 
object (true) or to return its width and height (false). The array object above 
shows both an icon and a drawing procedure (the box): 
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/drawing { 

{ItemBorderColor setcolor 1 1 14 14 rectpath stroke} 

{16 16} ifelse 
} def 

Use of these items follows the general pattern: 

□ A canvas is created for containing the items. This is generally done b} 
creating a window and getting its ClientCanvas. The window’s 
PaintClient procedure should include a call to paintitems. 

□ A dictionary (or array) of items is created using the /new message to t 
item class of interest followed by a /move message to this instance. 

n This collection of items is activated by calling forkitems. The items’ 
notification procedures will be used to perform the activities the progr 
desires. 

Here is a minimal example of this style. We create a window with a buttoi 
message item. The button’s notify procedure simply prints “Button Presst 
the message item. 

/win { 

/PaintClient {items paintitems} def 
} makewindowfromuser def 
/can win /ClientCanvas get def 

/notify {(Button Pressed!) /print items /message get send} def 

/items 50 diet dup begin 

/message (Message:) ( ) 

/Right {} can 0 0 /new Messageltem send 
10 10 /move 3 index send def 
/button (Button) /notify can 0 0 /new Button Item send 
1 0 30 /move 3 index send def 
end def 

/p items forkitems def 
This is the resulting window: 









^Ritton^ Message: Button Pressed! 
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Figure B-7 Typical Item Usage 



B.5. Labeleditem Subclass 
Details 



This section presents details on the use of the Labeleditem subclasses. 

□ Buttonitem: ItemValue is a boolean; true if pressed, false if not. Gei 
the ItemValue is never used; the NotifyUser is called to perform the 
button’s activity. Buttonitems differ from the rest of the Labeledltei 
not having an object and object location in the arguments to /new. 
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□ Cycleltem: ItemObject is an array of objects. ItemValue is the index of 
the currently displayed object in that array. The cycle starts at zero and 
progresses one each “push"’ of the item. NotifyUser is called when the 
cycle changes value. 

c Sliderltem: The object is an array consisting of three integers: the minimum 
value, the maximum value, and the initial value for the slider. The Item- 
Value is the current value of the slider, and NotifyUser is called when the 
button is released. You can be notified continuously by overriding 
ClientDrag: 

/ClientDrag {/ClientDrag super send NotifyUser} def 

□ Textitem: ItemValue is the current string being displayed. The object is 
the initial string. NotifyUser is called whenever there is any change to 
ItemValue. Text items differ from the others in the way they use the mouse. 
MouseDown activates the text item if it is not yet active, and changes the 
caret location if it already active. The item is de-activated by activating 
another text item or by exiting the parent canvas of the text item. Keyboard 
motion is available in the text item using standard Emacs control sequences. 

□ Messageltem: The object in a message is its initial value. This need not be 
text! Message items have two additional methods: /print and /printf. 

/print takes a single argument, generally a string, and displays it as the 
item’s new object, /printf has two arguments: a format string and an argu- 
ment array. See the previous chapter for sample usage. NotifyUser is called 
whenever a new message is posted. It should generally be an empty pro- 
cedure. ItemValue is the current message. 

□ Arrayltem: The object is an array of equal length arrays. The ’’inner” 
arrays are the subsequent rows. The sample array item was created by: 

(Arrayltem) [ 

[(One) (Two) /paneljext] 

[(Four) /drawing (Six)] 

] /Top /notify can 0 0 /new Arrayltem send 

ItemValue is an array of indices of the current selection and is initialized to 
[0 0]. NotifyUser is called from ClientUp if the ItemValue changed from 
its initial value. 
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News Operators 



This appendix lists all the current News operators, alphabetically first, then by 
type. 

C.l. News Operators, 

Alphabetically 



listenfile 


acceptconnection file 


listens for connection 


num 


arccos num 


computes arc cosine 


num 


arcsin num 


computes arc sine 


num 


arctan num 


computes arc tangent 


- 


awaitevent event 


blocks for event 


num 


blockinputqueue - 


block input events 


- 


breakpoint - 


suspends current process 


w h bits matrix proc 


buildimage canvas 


constructs canvas object 


canvas 


can vasto bottom - 


moves to bottom of sibling list 


canvas 


can vast otop - 


moves to top of sibling list 


- 


clipcanvas - 


clip to canvas boundary 


- 


clipcanvaspath - 


set current path to clip 


process 


continueprocess - 


restart suspended process 


color 


contrastswithcurrent boolean 


compare colors 


dx dy 


copyarea - 


copy current path to dx, dy 


- 


countinputqueue num 


returns count of input queue 


string 


createdevice canvas 


create new canvas 


— 


createevent event 


create an event 


- 


createmonitor monitor 


create monitor object 


canvas 


createoverlay canvas 


create overlay canvas 


- 


currentautobind boolean 


autobinding enabled? 




currentcanvas canvas 


current canvas 


— 


currentcolor color 


current color 


— 


currentcursorlocation x y 


returns mouse coordinates 


- 


currentlinequality n 


current line quality 


- 


currentpath shape 


return current path 


- 


currentprintermatch boolean 


return printermatch value 


- 


currentprocess process 


return current process object 


- 


currentrasteropcode num 


rasterop combination function 


- 


currentstate state 


returns graphicsstate object 
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— 


currenttime num 


returns a time value 


— 


damagepath - 


sets path to damage path 


- 


dumpsys - 


dump state to standard output 




ernptypath boolean 


tests current path 


— 


enumeratefontdicts names 


scans font dictionaries 


- 


eocii pcanvas - 


eoclip to current canvas 


dx dy 


eocopyarea - 


copy area to dx, dy 


- 


eocurrentpath shape 


returns current path 


canvas 


eoreshapecanvas - 


even/odd reshape of canvas 


file or string 


eowritecanvas - 


write canvas to file 


file or string 


eowritescreen - 


write screen to file 


any 


errored boolean 


use like stopped 


event 


express! nterest - 


queue input events 


- 


extenddamage - 


extend damaged path 


- 


eoextenddamage - 


extend damaged path 


stringl string2 


file file 


same as Adobe implementation 


proc 


fork process 


creates a new process 


string 


forkunix - 


forks a UNIX process 


canvas 


getcanvascursor font char char 


gets cursor for canvas 


canvas 


getcanvaslocation x y 


returns canvas location 


stringl 


getenv string2 


gets value of stringl in server 


- 


geteventlogger process 


get event logger process 


- 


getkeyboardtranslation num 


returns mode of translation 


- 


getmousetranslation boolean 


are events translated? 


file 


getsocketlocaladdress string 


return address of file 


file 


getsocketpeername string 


return name of host connected 


h s b 


hsbcolor color 


return color matching hs b 


canvas 


imagecanvas - 


maps canvas to current canvas 


boolean canvas 


imagemaskcanvas - 


analogous to imagemask 


canvas x y 


insertcanvasabove - 


insert above current canvas 


canvas x y 


insertcanvasbelow - 


insert below current canvas 


- 


keyboardtype num 


return type of keyboard 


process 


kill process - 


kills process 


process 


killprocessgroup - 


kills entire processgrow^ 


- 


lasteventtime num 


returns TimeStamp 


— 


localhostname string 


returns network hostname 


a b 


max c 


leaves maximum on stack 


a b 


min c 


leaves minimum on stack 


monitor proc 


monitor - 


exec proc with locked monitor 


monitor 


monitorlocked boolean 


checks state of monitor 


xy 


movecanvas - 


moves canvas to xy 


pcanvas 


newcanvas ncanvas 


creates a new canvas 


- 


newprocessgroup - 


creates a new processgroup 


array 


pathforallvec - 


analogous to pathforall 


- 


pause - 


suspends current process 


xy 


pointinpath boolean 


isxy in path? 


stringl string2 


putenv - 


alter value of stringl 




random num 


return random value 


string 


readcanvas canvas 


read string as canvas 
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event 


recallevent - 


remove event from queue 


event 


redistributeevent - 


enter event into queue 


canvas 


reshapecanvas - 


sets canvas to be path 


event 


revokeinterest - 


revoke interest in event 


rg b 


rgbcolor color 


set color to r gb value 


event 


sendevent - 


launch an event 


boolean 


setautobind - 


set autobinding 


canvas 


setcanvas - 


set current canvas 


font char char 


setcanvascursor - 


set cursor identifiers 


color 


setcolor - 


set current color 


xy 


setcursorlocation - 


set cursor to xy 


process 


seteventlogger - 


make process event logger 


object integer 


setfileinputtoken - 


add object to tokenlist 


boolean 


setkeyboardtranslation - 


is translation on? 


n 


setlinequality - 


set linequality value 


boolean 


setmousetranslation - 


sets mouse translation mode 


path 


setpath - 


set path to path 


boolean 


setprintermatch - 


set printermatch flag 


num 


setrasteropcode - 


set rasterop combination function 


graph icsstate 


setstate - 


set graphics state 


- 


startkeyboardandmouse - 


initiate server processing 


process 


suspendprocess - 


suspend process 


num 


tagprint - 


put num on output stream 


object 


typedprint - 


put object on output stream 


- 


unblockinputqueue - 


release input queue block 


dictionary key 


undef - 


undefine key from dictionary 


process 


waitprocess value 


wait until process completion 


file or string 


writecanvas - 


write canvas to file 


file or string 


writescreen - 


write screen to file 



C.2. News Operators, by 
Type 



The following operators are sorted by type. 



Canvas Operators 



w h bits matrix proc 
canvas 
canvas 



string 

canvas 



canvas 
file or string 
file or string 



buildimage canvas 
canvastobottom - 
canvastotop - 
cHpcanvas - 
clipcanvaspath - 
createdevice canvas 
createoverlay canvas 
currentcanvas canvas 
eoclipcanvas - 
eoreshapecanvas - 
eowritecanvas - 
eowritescreen - 



constructs canvas object 
moves to bottom of sibling list 
moves to top of sibling list 
clip to canvas boundary 
set current path to clip 
create new canvas 
create overlay canvas 
current canvas 
eoclip to current canvas 
even/odd reshape oF canvas 
write canvas to file 
write screen to tile 
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canvas 
c a n va s 




c canvas 
string 
canvas 
canvas 
file or string 
file or string 



getcanvaslocation x y 
imagecanvas - 
imagemaskeanvas - 
insertcanvasabove - 
insertcanvasbelow - 
movecanvas - 
newcanvas ncanvas 
readcanvas canvas 
reshapecanvas - 
setcanvas - 
writecanvas - 
writescreen - 



Event Operators 



num 



event 



event 

event 

event 

event 



awaitevent event 
blockinputqiieue -- 
countinputqueue num 
createevent event 
expressinterest - 
geteventlogger process 
getmousetranslation boolean 
lasteventtime num 
recallevent - 
redistributeevent -- 
revokeinterest - 
sen de vent - 
unblockinpiitqueue - 



.Mathematical Operators 



num arccos num 

num arcsin num 

numi arctan num 

a b max c 

a b min c 

- random num 



Process Operators 



crocess 



proc 



mLon 



process 
process 
or croc 



breakpoint - 
continueprocess - 
createmonitor monitor 
currentprocess process 
fork process 
forkunix - 
killprocess - 
killprocessgroup - 
monitor - 



... 

ail 

Tiicrosystems 



returns canvas location 
maps canvas to current canvas 
analogous to imagemask 
insert above current canvas 
insert below current canvas 
moves canvas to ;c y 
creates a new canvas 
read string as canvas 
sets canvas to be path 
set current canvas 
write canvas to file 
write screen to file 



blocks for event 
block input events 
returns count of input queue 
create an event 
queue input events 
get event logger process 
are events translated? 
returns TimeStamp 
remove event from queue 
enter event into queue 
revoke interest in event 
launch an event 
release input queue block 



computes arc cosine 
computes arc sine 
computes arc tangent 
leaves max on stack 
leaves min on stack 
return random value 



suspends current process 
restart suspended process 
create monitor object 
return current process object 
creates a new process 
forks a UNIX process 
kills process 
kills entire processgroug^ 
exec proc with locked monite 
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monitor 


monitorlocked boolean 


checks state of monitor 


- 


newprocessgroup - 


creates a new processgroup 


- 


pause - 


suspends current process 


process 


seteventlogger - 


make process event logger 




suspendprocess - 


suspend process 


process 


waitprocess value 


wait until process completion 


Path Operators 




dx dy 


copyarea - 


copy path to dx, dy 


- 


currentpath shape 


return current path 


- 


damagepath - 


sets path to damage path 


- 


emptypath boolean 


tests current path 


dx dy 


eocopyarea - 


copy area to dx, dy 


- 


eocurrentpath shape 


returns current path 


- 


extenddamage - 


extend damaged path 


~ 


eoextenddamage - 


extend damaged path 


X y 


pointinpath boolean 


xy in path? 


path 


setpath - 


set path to path 


File 


Operators 




listenf ile 


acceptconnection file 


listens for connection 


stringl string2 


file file 


same as Adobe implementation 


file 


getsocketlocaladdress string 


return address of file 


file 


getsocketpeername string 


return name of host connected 


num 


tagprint - 


put num on output stream 


object 


typedprint - 


put object on output stream 


Color 


Operators 




color 


contrastswithcurrent boolean 


compare colors 


- 


currentcolor color 


current color 


h s b 


hsbcolor color 


return color matching h s h 


r g b 


rgbcolor color 


set color to r g b value 


color 


setcolor - 


set current color 


Keyboard and Mouse 


Operators 




— 


currentcursorlocation x y 


returns mouse coordinates 


- 


getkeyboardtranslation num 


remms mode of translation 


- 


getmousetranslation boolean 


are events translated? 


- 


key boar dtype num 


return type of keyboard 


boolean 


setkeyboardtranslation - 


is translation on ■ 


boolean 


setmousetranslation - 


sets mouse translation mode 


“ 


startkeyboardandmouse - 


initiate server processing 
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Cursor Operators 

returns mouse coordinates 
gets cursor for canvas 
set cursor identifiers 
set cursor to x v 

Miscellaneous Operators 



- currentcursorlocation x y 

canvas getcanvascursor font char char 

font char char setcanvascursor - 

X y setcursorlocation - 



- currentautobind boolean 

- currentlinequality n 

- currentprintermatch boolean 

- currentrasteropcode num 

- currentstate state 

- currenttime num 

- dumpsys - 

- enumeratefontdicts names 

any errored boolean 

stringl getenv string2 

- localhostname string 

array pathforallvec - 

stringl string2 putenv - 

boolean setautobind - 

n setlinequality ~ 

boolean setprintermatch - 

num setrasteropcode - 

graphics state setstate — 

dictionary key undef — 



autobinding enabled? 

current line quality 

return printermatch value 

rasterop combination function 

returns graphicsstate object 

returns a time value 

dump state to standard output 

scans font dictionaries 

use like stopped 

gets value of stringl in server 

returns network hostname 

analogous to pathforall 

alter value of stringl 

set autobinding 

set linequality value 

set printermatch flag 

set rasterop combination function 

set graphics state 

undefine key from dictionary 
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bldf amiiy( 1) — build font family description 213 

cps(l) — construct C to POSTSCRIPT language interface 215 

aumpf ont(l) — dump font in another format 217 

journalling{\) — record and playback package 219 

kbd_mode(l) — change keyboard translation mode 221 

news__server(l) — NeWS server program 223 

psterm(l) 225 

newsdemos(6) — NeWS demonstrations 231 

newshost(l) — NeWS network security control 237 

psh(l) — NeWS PostScript shell 239 

psload(l) — display load average under NeWS 241 

:nan — on-line display of reference pages using NeWS 243 

psterm(l) — NeWS terminal emulator 245 

psview{\) — PostScript language previewer 247 

say(l) — execute POSTSCRIPT language fragment 249 

setnewshost(l) — set NEWSSERVER environment 251 

xdemos(6) — X Window System demonstration 253 

psio(3) — News buffered input/output package 255 
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USER COMMANDS 



BLDFAMILY(l) 



NAME 

bldfamily -* build font family description 
SYNOPSIS 

bldfamily [ -ddirname ] [ -ooutname ] [ -v ] names 
DESCRIPTION 

bldfamily scans a sets of NeWS font files and produces a NeWS font family file. A font family is a set of 
font files that are grouped together to provide a single PostScript language font. In the PostScript 
language, a font has a name, like Times-Roman, and can be rendered in many different sizes. A NeWS 
font file is an instance of a PostScript language font at a particular size. Font family files contain the 
information necessary for NeWS to pick the right bitmap font, 

bldfamily scans directory dirname for files with extension ".fb" or ",fm" and where the leading non-digit 
characters of the filename match one of the names . The family file that is built will be written to 
dirname loutnameM, 

If outname isn’t specified, it defaults to the first of the names . If dirname isn’t specified, it defaults to 
"$FONDIR" if defined, otherwise. If names isn’t specified bldfamily scans dirname for all font files and 
builds all the possible family files. 

OPTIONS 

—ddirname 

—ooutname 

-V 

EXAMPLE 

paper% dumpfont -d /usr/newfonts -n Boston boston*. vfont 
paper% bldfamily -d/usr/newfonts Boston 

The first command calls dumpfont and converts all the vfont files whose names match ’’ boston*. vfont" into 
NeWS format. It puts them into lusrinewfonts and changes their font name to Boston (it would have 
defaulted to boston). The second command calls bldfamily and scans lusrinewfonts for ”Boston*.fb” and 
builds a font family file for them, which will be called lusrInewfontsIBoston.ff, 

SEE ALSO 

dumpfont(l) 

DIAGNOSTICS 

filename isn’t a font file 

bldfamily has found a file that matches one of the names and has an appropriate exten- 
sion, but it isn’t a valid font file. You should probably ignore this message. 

TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 



Specifies the directory to scan and put the .ffam file into. 
Specifies the output font name 

Verbose - gives a more detailed description of what is going on. 
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CPS (1) 



NAME 

cps ~ construct C to PostScript language interface 
SYNOPSIS 

cps [ -c ] [ — D symbol ] [ -I filename ] [ *~i ] [ POSTSCRIPT language file ] 

DESCRIPTION 

CPS compiles a specification file containing procedure names and PostScript language code into a header 
file (filename. h) that can be included in programs. Only one input file can be specified, and if the 
f ilename .h file has been previously created, a backup copy of this file will be generated in the form 
filename . h . BAK before the new file is generated. 



The convention is for the input specification file to end in .cps. 

OPTIONS 

-c Compiles a PostScript language file for faster loading by News, and is not used to gen- 

erate a specification file for programs. For example, the following command line: 

cps -c < input_file > output_file 



-D symbol 



-I filename 



will convert the input Jile from the ascii form of the PostScript language, to the 
compressed binary form. When read by News, the output Jile will execute exactly the 
same as input Jle, except that it will be faster. The -c option will not work if the 
input Jile uses constructs like currentfile readstring, which are often used with the 
image primitive. 

Defines symbols to be passed onto the language pre-processor (cpp) which processes the 
input file. 

Specifies include files. Passed on to the pre-processor. 

Generates two specification files: one that contains only the procedures and PostScript 
language code that are user-defined, and one that contains other definitions required for 
the C-PostScript language interface. For example, and would be defined in the second 
file. The second file references the user-defined procedures as extern char. The first 
file is of the form filename.c, and the second file is of the form filename. h. . BAK files 
will be generated if the files already exist. 



This option is valuable for controlling the size of the cps include files in multiple source 
files. The filename. h would only need to be included once. Each source file would only 
need to include it’s specific filename. c file generated by this option. 

SEE ALSO 

News Manual - Chapter 9 "C Client Interface" 
cpp(l) 

TRADEMARK 

PostScript is a registered trademark of Adobe Systems, Inc. 
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DUMPFONT(l) 



NAME 

dumpfont - dump font out in some other format 
SYNOPSIS 

dumpfont [ -a|-bhv| ] [ -c comment ] [ -d dirname ] [ -f ] [ -n fontname ] [ -S ] [ -s /z ] [ -t ] [ -tv ] [ 
—ta ] filenames 

DESCRIPTION 

dumpfont reads in the set of named font files and dumps them out again according to the specified options, 
effectively converting the files from one font format to another, dumpfont is typically used to generate 
fonts for use with the NeWS window system. 

There are five types of font files that dumpfont can read: Sun standard vfont format, Adobe ASCII bitmap 
format, Adobe ASCII metric format, NeWS font format, and CMU (Andrew) format. The format of the 
input font is determined automatically by inspecting the file. It can write fonts out in one of three formats: 
Adobe ASCII, NeWS, and vfont. The default output format is NeWS. 

OPTIONS 

-a Selects Adobe ASCII output format. This is the format that you should use when tran- 

sporting fonts from one machine architecture to another. The output file extension will 
be ".afont". 

-b Selects NeWS output format (the default). The output file extension will be ".font". If 

the input file is an Adobe ASCII metrics file, the extension will be ".metrics". 

-V Selects vfont output format. The output file extension will be ".vfont". 

-vf Selects vfont output format. The output file extension will be ".vfont". Forces the char- 

acters to be fixed width. 



-c comment Sets the comment field of the font. The Adobe ASCII and NeWS font formats support an 
internal comment that accompanies the font. This is usually used to contain copyright or 
history information. It is normally propagated automatically. 

~d dirname Specifies the directory into which the font files will be written. If the FONTDER environ- 
ment variable is set, it is used as the default value. Otherwise, if the NEWSHOME 
environment variable is set, $NEWSHOME!fonts is used as the default value. Otherwise 
is used. 

-f n Sets the maximum length of an output filename (excluding extension) to n . When writing 

NeWS format files, NeWS normally constructs the output filename from the name of the 
font and its scaling factors. Some systems cannot cope with long file names, so this 
option can be used to heuristically squeeze the name. 

-n name Forces the output font name to be name , It is important to not confuse the name of the 

font with the name of the file that contains it. Some font formats (Adobe ASCII and 
NeWS) contain the name of the font internally. So given a 10-point Times-Roman font, 
its font name will be "Times-Roman", but its file name might be TimRomlOfont. 

-S Attempts to determine the size information of fonts by inspecting the bitmaps and apply- 

ing some heuristics. This is useful when reading vfonts (particularly those intended for 
printers like the Versatec) that are missing or have incorrect size information. 
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->s n Sets the point size of the font to n . Overrides any internal size specification 

-t Prints a short description of the fonts on standard output; a reformatted font file is no 

dumped. 

~tv Prints a move verbose description of the fonts on standard output; a reformatted font file 

is not dumped. 



-ta Prints a long description of the fonts on standard output; a reformatted font file is no 

dumped. You’ll get every scrap of information. 



SEE ALSO 

bldfamily(l), vfont(5) 



DIAGNOSTICS 

Bad flag: -C Unknown command like option 

Couldn’t write ... Error writing font file 
/: not a valid font. Unknown input file format. 

BUGS 

Should have been named convertfont . 
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NAME 

journalling - NeWS event record and playback package 

SYNOPSIS 

journalling 

DESCRIPTION 

The Journalling package allows you to capture NeWS mouse and keyboard events onto a file, and then play 
the file back. This results in NeWS acting like a player piano, faithfully duplicating the original user 
actions in real time. 

This package permits continuous replaying of a given file. Playback can be interrupted at any time by 
clicking one of the mouse buttons. 

Journalling also includes playback speed control, which allows you to slow down or speed up the playback 
rate. 

USAGE 

Invoking the journalling program will add a Journalling => menu item to the root menu. The Journal 
menu item in the News Applications => sub-menu does the same thing. Note that it will take a few seconds 
for journalling to load everything into the News server. 

There are five submenus under the main Journalling menu item: 

Control Panel - Brings up the Journalling control panel 

Start Recording - Start recording on the current Record file 

Stop Recording - Signals the end of recording 

Playback - Starts playback of the current Playback file 

Remove Journalling - Gets rid of all journalling menus and resources 

Note that Playback can be interrupted at any time by hitting one of the mouse keys. 

Selecting the Control Panel item brings up a control panel window. It contains the following items: 

RECORD, STOP, and PLAY buttons: These buttons perform the same function as the 
corresponding menu items. They also light up to indicate what action is currently taking place. 
They can be used interchangeably with the menu items. 

Record File: This text item allows you to specify the current file to record onto. It can be any 
valid filename on the server machine. Relative pathnames are taken to be relative to the directory 
that NeWS was started from. The default for the Record file is I tmpf NeWS journal. 

Playback File: The current file to playback from. It has the same characteristics as the Record 
File. 

Play Forever toggle switch: If this switch is on then Journalling will automatically repeat play- 
ing the Playback File. 

Playback Speed: Slider that scales the playback time. Positive values make playback speed up, 
negative values make playback slow down. This facility is dependent on the speed of the underly- 
ing hardware. It is not calibrated between different machines. 
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Done: The Done button will hide the Control Panel. It can be brought back up by selec^_^/ 
Control Panel menu item. The Zap window command has the same effect. 



TIPS FOR USING JOURNALLING 

When creating journals that will be replayed repeatedly, it is important to get rid of whatever windows ^ 
have created at the end of the journal. The state of the screen should be just as it was when the journal \ 
begun. Otherwise, the NeWS server will eventually run out of memory because you are continually ere 
ing new windows. Doing a Zxip from the All Windows menu at the end of the journal will provide 
desired effect. However, be sure that you then restart a Console window to catch system messages. 

There is a noticeable variation in performance on NeWS running on different kinds of machines; it r 
much faster on a Sun 4 than on a 3/50! This means that playing back a script recorded on a fast mach 
might not always work correctly on a slower machine. A given machine can handle NeWS events at sc 
maximum rate. The Playback Speed Control will allow you to adapt playback speed of a given script i 
fairly wide range of machines; unfortunately, this requires a bit of trial and error. 

Care must be taken when recording sequences that contain invocations of Unix programs, particul: 
when starting new applications. The mouse must not be clicked until the bounding box is up on the sen 
If the mouse is clicked early, the wrong window sizing will be made on playback, leading to unpredicU 
behavior due to the window not being where it was when recording. 

FILES 

${NEWSHOME}/lib/NeWS/joumal.ps Contains the low level journalling code, the control pj 

and menu code, and state button Lite Item code used 
the control panel. 

${NEWSHOME}/demo/joumalling ${NEWSHOME}lliblNeWSIjournaLps. 

SEE ALSO 

NeWS Manual 

BUGS 

The unpredictable behavior of playback due to the non-deterministic Unix scheduling mechanism and ^ 
eral operating environment make reliance on the Journalling package for critical functions unadvisable. 
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NAME 

kbd_mode - change the keyboard translation mode 
SYNOPSIS 

kbd_mode -a 1 -n | -e | -u 
DESCRIPTION 

kbdjnode sets the translation mode of the console’s keyboard (/dev/kbd) to one of the four values defined 
for KIOCTRANS in kb{^S). This is useful when a program which resets the translation mode crashes; for 
example, NeWS (when run from SunView) can sometimes leave SunView reading untranslated events. 

OPTIONS 
-a 

~-n 
-e 

-u 

FILES 

Idevikbd 

$NEWSHOMEfbinlkbdjnode 

SEE ALSO 

kb(4S) 



ASCII: the keyboard will generate simple ascii characters 

none: the keyboard will generate unencoded bytes - a distinct value for up and down 
on each switch on the keyboard 

events: the keyboard will generate SunWindows input events with ascii characters in 
the value field 

unencoded: the keyboard will generate SunWindows input events with unencoded 
bytes in the value field (this is the mode News currently uses). 
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NAME 

news server — NeWS server 
SYNOPSIS 

news_server [ PostScript ] 

DESCRIPTION 

The news^server command starts the News server. The News server is an interpreter for a subset of the 
PostScript language. The PostScript language was defined by Adobe Systems Inc. News supports many 
overlapping drawing surfaces, multiple lightweight threads of execution, and message-based interprocess 
communication. Details of the the structure of News are found in the NeWS Manual, 

OPTIONS 

[ PostScript ] 

The News server interprets the PostScript program given as an argument on the command line. 
If no PostScript language text is given on the command line, news_server executes 

(NeWS/init.ps) (r) file cvx exec &main 

This PostScript language fragment sets up News for its normal use as a window server. When 
specifying this argument, you probably should put single quotes around the “s fragment ” to pro- 
tect it from premature interpretation by the shell. The PostScript language files %stdin, 
%stdout, and %stderr have their normal meanings while this program is executing. 

FRAMEBUFFER 

Another option is defined by the FRAMEBUFFER environment variable. The device name (e.g., 
IdevIbwtwoO, IdevIcgtwoO) contained in FRAMEBUFFER tells News which frame buffer to 
display on. If FRAMEBUFFER is not defined then Idevifb is the default. 

USAGE 

The first thing that you should do is to start a terminal emulator which acts as a console. This console win- 
dow will display system messages and will prevent these messages from writing over your display. Bring 
up a console window by depressing the right mouse button and sliding the mouse to the right until the word 
‘Console' is displayed under the mouse cursor. Now release the right mouse. 

Compatibility 

NeWS may be run either from outside the SunView environment, or from inside the SunView environment 
by using o^^erview{\), NB: You must be sure that the FRAMEBUFFER environment variable used by the 
NeWS server matches the -d argument used by server matches the -d argument used by suntools. Both 
of these values default to / dev/ fb, so if one is changed, the other must be also: 

overview -w news_server 

While running News from outside SunView, SunView tool binaries may be executed as normal. Their 
windows will appear on top of all News windows, but will otherwise behave normally. 

Root Menu 

When News starts, using the standard init.ps, it paints the desktop gray and waits for the user to select a 
menu option. By default, menus pop up on the right mouse button. The standard root menu is (shown 
with the submenus hierarchy expanded): 

Applications => 

Terminals => 

Fixed Size => 

Console 

sun 

H19 

bitgraph 



Sun Release 3.4 Last change: 2 December 1987 223 




NEWSSERVER(l) 



USER COMMANDS 



NEWS_SERVER(1 



vtlOO 

wyse 

tvi925 

Console 
sun 
H19 
bitgraph 
VtlOO 
wyse 
tvi925 
Clocks => 

Plain 

Plain (seconds) 

Fancy 

Fancy (seconds) 

Load Average 
Calculator 
Journal 
Demos => 

(see newsdemo(6)) 

All Windows => 

Zap 

Open 

Close 

Flip 

Tidy 

Here 

Drop 

Top 

Bounce => 

Windows 

Icons 

All 

Stop 

SunViewl => 

Selection Transfer => 

NeWS to SunView Shelf 
SunView to News Shelf 
Applications => 
shelltool 
cmdtool 
mailtool 
textedit 
defaultsedit 
iconedit 
dbxtool 
perfmeter 
clock 
gfxtool 
console 
lockscreen 
Default .suntools 

User Interface => 
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Input Focus => 

Click to Type 
Follow Cursor 

Window Management Style => 

Rubber-band Box => 

Thin 
Thick 
Grid 
Zoom => 

Zoom Slow 
Zoom Medium 
Zoom Fast 
Flip Drag 
Look & Feel => 

News Default 
SunViewl 

Retained Windows => 

On 

Off 

Default 

Root Image => 

Group 

Plain 

Repair => 

Repaint All 
Reset Input 
Exit News => 

No, not really. 

Yes, really! 

Applications => 

This menu lets you start up a number of News applications. 

Terminals is a pull-right menu from which you can create a window using the psterm(l) terminal 
emulator program. If you select one of these terminals, you must drag out the exact size of the 
window in which the terminal emulator will run. There is another menu item called Fixed 
Startup, which has the same options as the Terminals menu. If you select one of the terminals 
from Fixed Startup, you need not specify the size and location of the terminal emulator; it will be 
created automatically in the lower-left comer of the screen. Selecting Console from either the 
Terminals menu or the Fixed Startup menu creates an H19 terminal emulator that is set up to 
receive console messages. 

Clocks is a pull-right menu from which you can create a clock. The Plain clock is a simple round 
clock. The Fancy clock is a stylish modem round clock. Both clocks can be create with an option 
to show the seconds. 

Load Average invokes the psload piogxdm. This program is a load average monitor. 

Journal causes a journalling mechanism to be loaded into News. In addition, a menu entitled 
“Journalling” is installed in the top level root menu. The journalling mechanism allows you to 
capture and playback user actions. See journalling(l). 



Demos => 
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Lets you run one of the many demonstration programs. They are described in newsdemos(^^^ 
All Windows => 

Provides you with the choices necessary to manage all the windows on your display at or 
Some of the operations are more fun ilian useful. 

Zap causes all the windows on the scieen to be destroyed. 

Open causes all the windows on the screen to be opened. 

Close causes all the windows on the screen to be closed. 

Flip causes all the windows on the screen to toggle between their open state and their closed st< 

Tidy causes all the open windows on the screen to be moved to their closest comer. All clc 
windows line up along the bottom edge of the screen. 

Close causes all the windows on the screen to be closed. 

Here Allows you to position all the w indows on the screen with successive clicks of the mouse 

Drop causes all the windows on the screen to “fall” to the bottom of the screen. 

Top causes all the windows on the screen to “rise” to the top of the screen. 

Bounce is a pull-right menu that is used to invoke a demo that is used to “bounce” 
around the screen. This demo is pairticularly slick when all the windows are retained. 
bounce just the open windows with the Windows command. You can bounce just the icons i 
the Icons command. You can bounce both with the All command. Stop terminates the bouncir 

Sun View 1 => 

As mentioned above, you can run existing Sun View 1 and SunW indows application concurre 
with News applications. 

Selection Tranter lets you exchange selections between News applications and SunView app] 
tions. News to SunView Shelf takes the current News selection and loads it onto the Sun\ 
shelf. A subsequent get operation in SunView will retreive the contents of the shelf. SunVie 
News Shelf takes the current SunView selection and loads it onto the News shelf. A subseq 
get operation in News will retreive the contents of the shelf. Note: There is a race cond 
between when you invoke one of these shelf transfer menu operations and when you subseque 
release the get key. Waiting a second or two between the two operations should avoid any p 
lem. 

Applications lets you invoke any of the following SunView applications: shelltool, cmdtool, 
tedity mailtooly defaultsedit, iconedity dbxtooL perfmetery clocky gfxtooly consolcy lockscreen. 
Default .suntools entry starts up the standard set of SunView applications, which includes a 
sole window, a text editor, a clock, a mail handler, and a terminal emulator. 

User Interface => 

The User Interface menu lets you alter a number of user interface options. 

Input Focus is a pull-right that provides you with a choice of keyboard focus mechanisr?^^t 
to Type forces input to occur in whichever window you last clicked the mouse (independei 
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current cursor location). Follow Cursor forces the input focus to shift to whichever window the 
cursor is currendy in. 

Window Management Style pull-right provides you with a number of options for controlling the 
default behavior of your windows. The Rubber-band Box menu controls the appearance of the 
rubber-band rectangle that appears when you specify window size; the choices are Thin, Thick and 
Grid. The Zoom menu controls the speed with which windows zoom into icons and vice versa; 
the choices are Zoom Slow, Zoom Medium and Zoom Fast. Flip Drag toggles the method of mov- 
ing windows between dragging the entire window and dragging just its frame. 

Look & Feel is a pull-right that allows you to toggle between the standard News look and feel and 
the SunViewl look and feel. Both windows and menus are altered to reflect the chosen look and 
feel. 

Retained Windows is a pull-right that allows you to choose the image saving behavior of newly 
created windows. If you turn retention On, windows redisplay very quickly, at the expense of 
more main memory usage. If you turn retention Ojf, applications redisplay by repainting their 
image, not by letting the system do it from an image stored off-screen. The Default setting is 
retained for one bit deep frame buffers but not for deeper frame buffers. 

Root Image is a pull-right that controls the color or pattern on the background (root) window. 
Select Plain to get your root window back to the default background. Select Group to show an 
image that mentions News and shows the Sun logo. 

Repair => 

Allows you to reset the input mechanism {Reset Input) or to repaint all the windows {Repaint All). 
Exit News => 

This menu allows you to exit News gracefully. It is done as a menu in order to avoid accidental 
invocation. 

Window Management 

The standard window management package provides for window manipulation via a pop-up menu invoked 
from within the frame of a window. Certain functions are also available via accelerators. Here is the win- 
dow management menu (it is found under the Frame pull-right): 

Move Lets you move the window by dragging it around with the mouse. Click a mouse button to leave 
the window at its new location. 

Move Constrained 

Lets you move the window, with motion constrained either vertically or horizontally. If you click 
in the left or right part of the window’s frame, you can move the window only horizontally. If you 
click in the top or bottom part of the window’s frame, you can move the window only vertically. 
Click once more to leave the window at its new location. 

Raises this window above all of the other windows. 

Pushes this window below all of the other windows. 

Causes the current program to exit. 

Allows you to change the size and placement of a window. Click where you want the upper left 
comer of the window to be, then drag out a rubber-band rectangle and click where you want the 
lower right comer to be, just as if you were creating a new window. The window will be resized 
and moved to the rectangle you just swept out 

Stretch Comer 

Allows you to change a window’s size by dragging one comer, leaving the opposite comer fixed 
where it is. Click a button when the mouse is near the comer you wish to drag; then click again 



Top 

Bottom 

Zap 

Resize 
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when the rubber-band rectangle is the size you want it to be. 

Stretch Edge 

Allows you to drag a window’s edge, just like dragging a comer. Click near the edge you want t 
drag, and then click again when you have placed it. 

Close Closes this window into an icon. 

Redisplay 

Causes the window to redisplay itself. 

You can use accelerators instead of the menu to manage windows. To raise a window, click the left butte 
in the window’s frame. To drag a window, press the middle button in the window’s frame, and drag th 
window into position with the button still down. To close the window into an icon, click the left button i 
the cycle glyph in the upper left comer of the window. To resize a window, click the left button in tf 
resize glyph in the lower right comer of the window. 

You can use similar management functions on icons as well as on windows. You can bring up a windo 
management menu over an icon by holding down the right button anywhere in the icon. This menu is sim 
lar to the menu for windows, except that it contains the following entries: Move, Top, Bottom, Zap, Opei 
Open&Resize, and Redisplay, The only new function is Open<ScResize, This function opens an icon into 
window that you drag out with the mouse. This is in contrast to Open, which causes the window to ope 
into its original shape. You can use accelerators on icons, too. You can click the left mouse button on £ 
icon to open it, and you can drag an icon to a new location with the middle button. 



Interpreter Access 

The standard init.ps file starts a server listening on port 144 (and then 2000) for client connections. Yc 
can use a program called psh{\) to connect to this port. At this point, you are talking to a POST^JLII 
language interpreter, and you can interact with it in the normal way. However, any errors you mak^^ii: 
the server to break the connection. To put yourself into an environment that is more forgiving of error 
you must type executive after you connect. For example, 

paper% psh 
executive 

Welcome to NeWS Version 1.1 

Type quit to the interpreter to exit psh. 

Remote Access 

See newshost(l) for information about allowing remote hosts to start applications on your local machin 
The default is that other machines can’t open connections to your News server. 

News Sockets 

If there is no socket specified in the NEWSSOCKET environment variable or in user .ps. News will t 
to listen on socket 144. Since 144 is a privileged socket, unless news_server is running as root, tl 
attempt to listen on 144 will fail, and the News server will then try to listen on socket 2000. This ord 
of consideration may be overridden by setting the NEWSSOCKET environment variable. The followir 
shell archive allows you to run two News servers on two displays: 

#! /bin/sh 

FRAMEBUFFER=/dev/bwtwoO NEWSSOCKET=%socketl2000 news_server & 
FRAMEBUFFER=/dev/cgtwoO NEWSSOCKET=%socketl2 0 0 1 news_server & 
sleep 5 

adjacentscreens /dev/bwtwoO --r /dev/egtwoO 
The socket on which News listens can also be set in your user . ps file with a line of the form: 



228 



Last change: 2 December 1987 



Sun Release 3 




NEWS_SERVER( 1 ) 



USER COMMANDS 



NEWS_^SERVER(1) 



/NeWS_socket (%socketl2001) def 



This will override any socket specified in the NEWS SOCKET environment variable. 

FILES 

If newsjerver is unable to open a file whose name doesn’t start with /, and which can’t be found in your 
home directory or the directory you started News from, it inserts ${NEWSHOME}llib at the front of the 
name and tries again. 



${NEWSHOME}/lib/NeWS/*.ps 

${NEWSHOME}/fonts/* 

$ {NEWSHOME }/bin/news_server 
7user.ps 



Startup PostScript language programs. 

Font Library 
the News server 

user-definable server customizations; loaded after other 
system *.ps files 



7startup.ps user-definable server customizations; loaded before other 

system *.ps files 

The FRAMEBUFFER environment variable specifies the default frame buffer for News. It defaults to 
Idevifb, 



SEE ALSO 

psh(l), psterm(l), psview(l), say(l), newsdemos(6), xdemos(6), joumalling(l), kbd_mode(l), 
newshost(l), psload(l), psman(l), setnewshost(l) 

NeWS Manual 

PostScript Language Reference Manual, Adobe Systems Inc., Addison-Wesley 

BUGS 

Some parts of the PostScript language have yet to be implemented. See the chapter in the NeWS Manual 
entided Omissions and Implementation Limits. 

The NeWS server is not yet completely robust when it runs out of memory. This out of memory condition 
occurs because swap space has been used up. Swap space is a resource that is shared by all the processes 
running on your machine. News has been designed to print a message on the console about being low on 
memory when it gets very close to being out of memory. If you see this message then you should immedi- 
ately reduce the stress on swap space by terminating some large processes [see pstat(8) with the -s flag]. If 
News does completely run out of memory, and it can’t recover, then it is designed to print a message on the 
console about being out of memory and aborting. 



When running SunViewl program, you may see many “Window display lock broken...” messages. You 
should have a console window for these message to appear in so as to avoid trashing the screen. 

TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 
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NAME 

News demos - News demonstrations 
SYNOPSIS 

Demos menu item in the News root menu 
OVERVIEW 

The Demos pull-right menu provides access to several News demonstration programs. These programs are 
intended to demonstrate News graphics and user interaction capabilities. 

Many of these programs are written in the extended version of the PostScript language understood by 
News, using the psh{\) program, psh simply opens a connection to the News server and sends News com- 
mands to it 

Unless described otherwise, you must specify a window for the demo when you start it When a small box 
appears by the cursor, you should click (and let go of) the right mouse button to indicate where you want 
one comer of the window to be. Then, as you move the mouse, a rubber-band box expands and contracts 
to show a window region. Click the right mouse button again to indicate where you want the opposite 
comer to be. You should not hold down the right button while defining the box. 

DESCRIPTION 

The Demos menu is available as a pull-right item from the News root menu. This menu contains the fol- 
lowing entries: 

Animation => 

Bounce 

Spin 

Wink 

Icosahedron 

Icosahedron screensaver 
Color => 

Color Cube 
Color Wheel 
Color Names 
Games => 

Go 

Bxkgammon 
Images => 

Display Scanned Image 
Image Rotate 
Image Scale 
Image Stencil 
Image Spin 
Catalyst 
Line Drawing => 

Escher’s fish 
Lines 

Rubber-band 

Vectors 

World 

Miscellaneous => 

Flags 

Item Demo 
Pie Chart 
Spiral 

Previewer => 

Golfer 
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Rose 

Shuttle 

Nozzle 

Overview 

Text => 

Text 

Text (scaled) 

Language Demo 
Icon Browse 
X.IO Demos => 

Run a Demo => 

Analog Clock 
Load Average 
KiU X Server 



Animation => 

The Animation pull-right item brings up a menu that contains several demonstrations of NeW 
animation capabilities. 

Bounce bounces a moving puck around inside of a window. You can use the menu inside the w 
dow to stop and start the puck, to change its size and color, and to change the speed at which 
puck bounces. You can drag the Bounce window while it is running; this demonstrates Ne^ 
lightweight process mechanism. 

Spin displays a spinning globe. It is best to select a small (1 inch x 1 inch) area for this de i^-^ 

Wink displays a pair of eyes in the middle of the screen, one of which winks at you. 

Icosahedron displays a bouncing 20 sided regular solid with the hidden lines removed. Due to 
computation necessary to figure the hidden lines, this demo may run faster if the program is run 
another machine. 

Icosahedron screensaver is like icosahedron^ but runs on top of all visible window. This progr 
goes away with a click of a mouse button. 

Color => 

The Color pull-right item brings up a menu that contains programs that demonstrate some 
NeWS’ color capabilities. Other programs will display in color, what distinguished the progra 
in this menu is their focus on color. 

Color Wheel draws a wheel of colors inside a window. If NeWS is running on a monochro 
display, it uses gray values instead of colors. You can use the menu to switch between gray ; 
color, and to vary the number of shades, the saturation, and the intensity of the colors displayed 

Color Cube is similar to the Color Wheel in that it displays colors and gray levels; howevei 
presents them in a different format Its menu lets you alter the presentation of the colors i 
manner similar to Color Wheel, 

Color Names shows you the correspondence between color names in the color dictionary 
implemented by NeWSicolors,ps) and their colors on the screen. This program uses scrol^^ 
access all the colors. In addition, there is an interesting use of the lite menu package to ^ J 
horizontal menu bar and menus with rows and columns. The menu is used to control text co 
font, face and size. 
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Games => 

The Games pull-right item brings up a menu with available games. 

Go is a simple program that puts up a Go board with which you can interact by placing and 
removing stones. Thus, you could play a game of go with someone else while seated in front of 
the screen. It is intended as a simple (but complete) application to show programmers how C, cps, 
and NeWS interact. The tutorial part of the NeWS Tutorial and Cookbook describes the internals 
of this program. 

Backgammon is a game that puts up a backgammon board and will actually play against you. This 
program is a port of gammontool, so see its man page for further documentation. 

Images => 

The Images pull-right item brings up a menu that contains several demonstrations of NeWS’ 
imaging capabilities. Each program (except for Image Scale) lets you select the image to display 
by means of a pop-up menu. You bring up the menu by clicking the right mouse button inside the 
window (not in the window’s frame). 

Display Scanned Image creates a window and displays an image inside of it. The image will be 
scaled to fit exactly within the window boundaries, regardless of its original aspect ratio. 

Image Rotate displays ten rotations of an image in a pinwheel arrangement. 

Image Scale takes the bitmap image of a turkey (from the PostScript Reference Manual, page 171) 
and scales it as many times as will fit inside the window. 

Image Stencil demonstrates NeWS’ capability of pushing an image through an arbitrary path, or 
stencil. The right button menu brings up a menu giving a choice of several stencils in addition to 
the selection of the image to be displayed 

Image Spin demonstrates NeWS’ image rotation capability. After you bring up the window, the 
server waits for you to define another rubber-band square with the mouse. Press the right mouse 
button where you want the lower left comer of the image to go and then release the button where 
you want the lower right comer of the image. The image is rotated and scaled to fit between the 
two points. The right button menu has an additional menu item. Spin, which lets you specify a 
different rotation for the image. 

Catalyst shows images digitized from Sun’s Catalyst Third Party Software catalog. 

Line Drawing => 

This pull-right item brings up a menu with demonstrations of line drawing. 

Eschers fish draws the famous Square Limit created by M. C. Escher. The demo is a 260-line 
recursive NeWS program that draws a large number of vectors. You can use the menu to vary the 
complexity of this drawing. 

Lines creates a window with a line pattern inside of it You can can alter the number of lines 
drawn from the pop-up menu inside the window. On color screens, the line pattern is displayed in 
a rainbow of colors. 

Rubber-band demonstrates how responsive NeWS can be when interacting with you. When you 
bring up the window, NeWS draws a rubber-band line from a comer of the window to the current 
mouse location. This line will track the mouse as you move it around on the screen. When you 
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click a mouse button, NeWS tracks the mouse with a rubber-band curve instead of a lii^_^C 
more click kills the window. 

Vectors is a demonstration of NeWS’ vector-drawing capabilities. The demo draws four spa 
ships inside its window, composed of over 7,000 vectors. 

World displays a geographic projection of the Western Hemisphere. 

Miscellaneous => 

This pull-right item brings up a menu with miscellaneous demonstrations. 

Flags displays flags of many nations, in color if possible. You can use the menu to display ju: 
single flag or all the flags at once. 

Item Demo is a demonstration of user interface items. The set of items includes buttons, slid 
cycles, and text areas. All of the items can be dragged around with the mouse. 

Pie Chart draws a business pie chart with slices of the pie filled with varying colors. 

Spiral draws a simple spiral pattern. 

Previewer => 

This pull-right item brings up a menu with demonstrations of NeWS’ PostScript language i 
viewing capabilities. The program psview is used to display PostScript language files ou 
from other programs, e.g.. Frame's Frame Maker, AutoCAD, and Adobe s Illustrator, 

Golfer and Rose were produced using Adobe's Illustrator program. 

Nozzle and Shuttle were produced using AutoCAD. 

Overview was produced using Frame's Frame Maker program. This is a multi-page docur 
that provides an overview of NeWS’ capabilities. 



Text => 

This pull-right item brings up a menu with demonstrations of NeWS’ text capabilities. 

Text writes text inside a window in several styles. The right button brings up a pop-up menu 1 
which you can select the font (under the Font pull-right), the point size, the colors, and the te 
be shown. The text shown can be either some sample text or a list of all characters in the ch 
font. 

Text (scaled) demonstrates NeWS’ ability to simulate the arbitrary scaling of text using onl> 
map fonts. The line spacing and intercharacter spacing are varied so that a continuous ranj 
sizes can be simulated with a fixed number of bitmap fonts. 

Language Demo shows that NeWS can support several different languages. You can select oi 
a variety of languages from the pop-up menu, causing both the menu and the text to be displ 
in the chosen language. 

IconBrowse brings up a large window that displays icons from the Icon font. You use th^^ 
control the range of characters displayed and to change the font from which they are dispWi^ 
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X.IO Demos => 

This pull-right item brings up a menu with a demonstration of a partial X.IO emmulation package. 
See xdemos.6 for further information. 



FILES 

$NEWSHOMEIUblNeWSldemomenu.ps 

News code for the demo menu and some of the demo programs. 

$NEWSHOMEIdemol^ demo programs not built into the demo menu. 

SEE ALSO 

psh(l), psterm(l), psview(l), say(l), xdemos(6) 

NeWS Manual 

PostScript Language Reference Manual , Adobe Systems Inc., Addison-Wesley 
TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 
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NAME 

newshost - NeWS network security control. 

SYNOPSIS 

newshost add [ hosts ] 

or newshost remove [ hosts ] 
or newshost show 

DESCRIPTION 

Newshost is a shell command that manipulate the registry of hosts that are allowed to connect to the NeWS 
server. The identity of the NeWS server whose registry will be manipulated is determined by the NEWS- 
SERVER environment variable. The variable /NetSecurityWanted (in the News systemdict) may be set to 
false to disable the security mechanism. 

newshost add adds the named hosts to the registry, 

newshost remove removes the named hosts from the registery, 

newshost show prints out a list of the hosts in the registry. 

SEE ALSO 

NeWS Manual 
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NAME 

psh - News PostScript shell 

SYNOPSIS 

psh [ files ] 

DESCRIPTION 

psh opens a connection to the NeWS server and transmits the file arguments (or stdin if no files are 
specified) to it. Any output from NeWS is copied to stdout. The files should be PostScript programs for 
the NeWS server to execute. 

A common use for psh is in creating applications written entirely in the PostScript language. First, type 
your PostScript program into a file. Then, type as its first line: 

#! /usr/NeWS/bin/psh 

If you now make the file executable (with chmod ) you can invoke it by name from the shell, and UNIX 
will use lusrINeWSIbinfpsh to execute it. psh will in turn send your program to the NeWS server. 

SEE ALSO 

sh(l), say(l) 

NeWS Manual 

TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 
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NAME 

psload - display load average under NeWS. 

SYNOPSIS 

psload [ -u update ] [ -h history ] 

DESCRIPTION 

Psload displays a graph in a NeWS window of the system load average. The graph is updated every 
update minutes, and contains information spanning an interval of history minutes. Update defaults to 0.083 
minutes (5 seconds) and history defaults to 10 minutes. 

SEE ALSO 

NeWS Manual 
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NAME 

psman - display reference manual pages; find reference pages by keyword 
SYNOPSIS 

psman [ section ] title 
psman -k keyword 

DESCRIPTION 

psman displays information from the reference manuals. It can display complete manual pages that you 
select by title. It can display one-line summaries selected by keyword (-k). 

When -k is not specified, psman formats a specified manual page by title. A section y when given, applies 
to the title that follows it on the command line, psman looks in the indicated section of the manual for the 
title, section should be a digit. If section is omitted, psman searches all reference sections (giving prefer- 
ence to commands over functions) and prints the first manual page it finds. If no manual page is located, 
psman prints an error message. 

The following line instructs psman to look in section 8 of the reference manual for the ypwhich(8) manual 
page: 



babylon% psman 8 ypwhich 

If the NeWS server is not available psman formats for a teletype and pipes its output through more(l). 
Otherwise, psman formats for a typesetter and pipes its output through psview{l). 

OPTIONS 

— k keyword ... 

psman prints out one-line summaries from the whatis database (table of contents) that contain any 
of the given keywords. 

ENVIRONTVIENT 

MANPATH If set, its value overrides fusrlman:$NEWSHOMEIman as the default search path. 

SEE ALSO 

cat(lV), col(lV), eqn(l), more(l), nroff(l), tbl(l), troff(l), whatis(l), man(7), catman(8) 
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NAME 

psterm — NeWS terminal emulator 
SYNOPSIS 

psterm [ options ] [ command ] 

DESCRIPTION 

psterm is a -based terminal emulator program for NeWS. When invoked, it reads the letcftermcap 

entry for the terminal named by the -t option, or by the TERM environment variable, and arranges to emu- 
late the behavior of that terminal. It forks an instance of command (or, by default, the program specified 
by the SHELL environment variable, or csh if this is undefined), routing keyboard input to the program 
and displaying its output. 

psterm scales its font to make the number of rows and columns specified in the letcftermcap entry for the 
terminal it is emulating fit the size of its window. It also responds to (most of) the particular escape 
sequences that termcap defines for that terminal. 

OPTIONS 

~C route f dev! console messages to this window, if supported by the operating system, 

-f Bring up a reasonably-sized terminal in the lower-left comer of the screen (or in the location 
specified with the — xy option) instead of having the user define its size and location. 

-w wait around after the command terminates. 

frame label 

Use the specified string for the frame label. 

— il icon label 

Use the specified string for the icon label. The icon label normally defaults to the name of the 
host on which psterm is running. 

-li lines specifies the height of the window in characters. 

—CO columns 

specifies the width of the window in characters. 

-xy X y specifies the location of the lower left hand comer of the window (in screen pixel coordinates). 

-bg causes psterm to place itself in the background by disassociating itself from the parent process and 

the controlling terminal. If psterm is invoked with rsh{\\ this option will cause the rsh command 
to complete immediately, rather than hang around until psterm exits. 

-Is causes psterm to invoke the shell as a login shell. In addition, any specified command will be 
passed to the shell with a -c option, rather than being invoked directly, so that the shell can estab- 
lish any environment variables that may be needed by the command. Further, if psterm is invoked 
via rsh{\\ the host at the other end of the rsh socket will be used as the server, unless a NEWS- 
SERVER environment variable is present. 

-pm specifies that a psterm should enable page mode. When page mode is enabled and a command 

produces more lines of output that can fit on the screen at once, psterm will stop scrolling, hide the 
cursor, and wait until the user types a character before resuming output. When psterm is blocked 
with a screenful! of data, typing a carriage return or space will cause scrolling to proceed by one 
line or one screenful, respectively; any other character will cause the next screenfull to appear and 
be passed through as normal input. This mode can also be enabled or disabled interactively, using 
the Page Mode menu item. 

SELECTION 

Clicking the left mouse button over a character selects that character. Clicking it beyond the end of the line 
selects the newline at the end of that line. Clicking the middle mouse button over a character when a pri- 
mary selection does not exist in that window selects that character. Clicking the middle mouse button over 
a character when a primary selection does exist in that window extends or shrinks the selection to that char- 
acter. 
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Note that selections are made by clicking. Mouse tracking is not implemented yet. 

The Copy key (L6) copies the primary selection to the shelf. The Paste key (L8) copies the contents < 
shelf to the insertion point . 

If you make a selection while holding down the Copy key, the selection will be a secondary sele 
Subsequently letting go of the Copy key copies the secondary selection to the shelf and deselects the s 
dary selection. 

Making a selection while holding down the Paste key also makes a secondary selection. It pastes th 
mary selection to the location of the secondary selection and deselects the secondary selection. 

Copy and Paste of both primary and seconckiry selections work across separate invocations of psterm. 
do not work between psterm and SunView. However, a mechanism does exist for transferring a Sur 
selection to the News shelf, and vice versa. See the description of Selection Transfer in news_server(l 

MENU ITEMS 

Psterm adds two items to the top of the standard menu associated with the right hand mouse button, 
items permit the page mode and automatic margin modes to be turned on and off. Menu items c 
according to the state of each mode. For example, if page mode is enabled, the menu item will in 
“Page Mode Off’. 

FILES 

/etc/termcap to find the terminal description. 

SEE ALSO 

news_sen?er{\) 

NeWS Manual 

BUGS 

Emulating some terminal types works better than others, largely because there are incomplete 
entries for them. 

A large number of termcap fields have yet to be implemented. 

Page Mode gets easily confused. 
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NAME 

psview - PostScript language previewer for NeWS 
SYNOPSIS 

psview [ PostScript language-file ] 

DESCRIPTION 

Psview puts up a window and runs the user’s PostScript language code in it. Psview uses a portion of the 
window that has the proper aspect ratio for a standard letter-size page in portrait orientation. 

If PostScript language-file is specified, the PostScript language code is taken from that file. If no argu- 
ment is given, or if a is given as the argument, psview reads the PostScript program from standard 
input. 

Psview lets you flip through the pages. Page boundaries are determined by locating the %%Page: com- 
ments. Psview provides a slider to move to any page, and a menu to go to the first, previous, next or last 
page. Clicking the left mouse button goes to the next page. 

SEE ALSO 

psh(l), say(l), newsdemos(6) 

NeWS Manual 

PostScript Language Reference Manual , Adobe Systems Inc., Addison-Wesley 
TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 

BUGS 

Assumes a syntactically valid PostScript language file. 
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NAME 

say ~ execute PostScript language fragment 
SYNOPSIS 

say [ options ] [ strings ] 

DESCRIPTION 

say connects to the NeWS server and displays the strings provided on the command line in a window. An 
option is provided to interpret the command line, or the standard input, as a PostScript program to be exe- 
cuted by the server. 

say is used to implement some of the NeWS demo programs. This technique allows window applications to 
be shell scripts. 

OPTIONS 

-hstring 

Use string as the title for the window. 

-c Center the text in the window. 

-p The command line contains a PostScript program rather than simply text strings. 

-P The standard input contains a PostScript program, which is executed after the PostScript 

language commands on the command line (if any). 

-r Make the window round. 

-snn Use nn as the point size of the text. 

-w Wait for the window to be destroyed. The default is for the window to vanish when execution of 
its PostScript program is finished. 

-W Do not create a window for the PostScript to be executed in. This can be used to implement 
operations that do not require a window; for example toggling drag mode in the window manager, 
or running PostScript language code that creates its own window. 

-XXX, yyy 

The first xxx,yyy pair of numbers sets the X and Y coordinates of the window. If a second 
-xxx,yyy command line option is given, it sets the size of the window. 

USAGE 

Older programs that use say solely to send PostScript to the News server (by specifying the -P -w -W " ” 
options to say ), should be converted to use psh (1 ). 

SEE ALSO 

psh(l), news_server(l) 

NeWS Manual 

PostScript Language Reference Manual , Adobe Systems Inc, Addison-Wesley 
TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 
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NAME 

setnewshost - generate a string for the NEWSSERVER environment variable 
SYNOPSIS 

setnewshost hostname 
DESCRIPTION 

setnewshost generates and prints the proper value of the NEWSSERVER environment variable for the 
given hostname. If NEWSSERVER is set then NeWS clients will attempt to connect to the server it points 
to rather than the local host. 

The format of the NEWSSERVER environment variable is as follows: 
decimal-address . portU ; hostname 

For example, if the host called “paper’ ’ has address 192.98.34.1 18, the NEWSSERVER variable should be 
set to “3227656822,2000;paper” so that NeWS clients will connect to the NeWS server on “paper”. 
setnewshost simply calculates this string and sends it to standard output. This is not its most convenient 
form, however. C-shell users can define the following alias: 

alias snh ’setenv NEWSSERVER ‘setnewshost \!*“ 

and System V Bourne Shell users can define the following function: 

snh 0 { 

NEWSSERVER-‘semewshost $*‘ 
export NEWSSERVER 

} 

Both forms let you simply type ‘snh hostname' to set the NEWSSERVER environment variable automati- 
cally. 

SEE ALSO 

psh(l) 

NeWS Manual 

BUGS 

The host table entry must have exactly the following format: a.b.c.d<mZ)> hostname. 

If you use the snh alias or shell function, and the hostname you give is unknown, or you give too many or 
too few arguments, the NEWSSERVER variable will be trashed. 
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NAME 

xdemos - X Window System demonstration 
SYNOPSIS 

X Demos menu item in the NeWS root menu 
DESCRIPTION 

The News X Demos are some programs that demonstrate a small subset of the X Window System (ver- 
sion 10) protocol running under NeWS. The X server is written almost entirely in the PostScript 
language; the code is contained in the file $NEWSHOMEIliblNeWSlX10.ps. 

The X Demos pull-right menu has two items: Run a Demo and Kill X Server, If the X server is not run- 
ning, the second menu item will have no effect. 

RUNNING DEMOS FROM THE MENU 

In order to start an X demo from the NeWS menu, you must pull right from the Run a Demo menu item. 
This reveals a number of demo programs: Analog Clock and Load Average. Selecting one of these starts 
up the corresponding X program. If the X Server has not yet been started, it will be started automatically. 
The demonstration programs do not bring up windows in the standard NeWS style; they instead conform to 
the standard X style, which is as follows. First, the name of the program appears in a small window in the 
upper left-hand comer of the screen. Then, a flickering rectangle or square appears at the current cursor 
location. This rectangle tracks the motion of the cursor. At this point, you can do one of three things: 

Click the left button. This brings up a window of default size at the current cursor location. 

Drag with the middle button. If you hold down the middle button, drag the mouse, and then 
release the middle button, you can drag out a rubber-band rectangle that specifies the window’s 
location and size. 

Click the right button. This brings up a window of default size at the default location. 

If you select Kill X Server while any X demos are active, they will be killed along with the server. 
WINDOW MANAGEMENT 

In the X Window System, the only way to move or resize windows is to use a window manager program. 
Unfortunately, no X window managers work under NeWS as yet. In order to provide window management 
facilities to X windows running under NeWS, a special window management menu is made available in all 
X windows. This menu is accessible from the right mouse button when the cursor is over an X window 
and it contains the following items: Move, Redisplay, Resize, and Quit. These functions should be self- 
explanatory. 

RUNNING DEMOS FROM A SHELL 

In order to run X demos from a shell (on the local machine or on a remote machine) one must set the 
DISPLAY environment variable properly. The NeWS X server listens for connections on port 5901, which 
means that the DISPLAY variable should contain the string “hostname:!” so that X clients will connect to 
the proper location. After DISPLAY is set properly, one can start up X demos in the normal X fashion. 

SEE ALSO 

newsdemos(6) 

NeWS Manual 

BUGS 

No byte swapping is done. 

Only a small subset of X requests is implemented. In particular, only programs like xclock and xload. 

The NeWS X Server accepts only internet-domain connections. UNEX-domain connections are not sup- 
ported. 
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Running the X demos from the menu can freeze the screen and input if you have a line in your . 
faults file similar to the following: MakeWindow .Freeze: on Turning on this option causes X clien 
to issue a slightly different set of requests, two of which the X demo do not handle. The work-around is i 
change the line in . xdef aults to: .MakeWindow .Freeze: off 

$NEWSHOME/lib/NeWS/demomenu .ps contains an error which causes the X demos to not run somt 
times. The work-around is to replace the following lines in $NEWSHOME/lib/NeWS/demomenu.p: 
% do "setenv DISPLAY localhostir (DISPLAY) (localhost:1) putenvwith: % do "setenv DISPLA 
‘hostname‘:1” (DISPLAY) localhostname (:1) append putenv 

The following is not really a bug as much as an exposure of the NeWS/X interface. X demo windows wi 
not respond to ‘Repaint All’ requests from the root menu, or ‘Zap AH’, ‘Open All’ requests from the ‘A 
Windows’ menu. The ‘Repaint AH’ problem is due to a known inadequacy of the current X emulator den^ 
package. ’Zap AH’ and other selections from the ‘AH Windows’ menu have no effect since X and NeW 
exist, in essence, in two different worlds. 

TRADEMARK 

PostScript is a registered trademark of Adobe Systems Inc. 
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NAME 

psio News buffered input/output package 

SYNOPSIS 

#include ”psio.h” 

PSFILE *psio_stdin; 

PSFILE +psio_stdout; 

PSFILE *psio_stderr; 

DESCRIPTION 

The functions described here constitute a user-level I/O buffering scheme for use when communicating 
with News. This package is based on the standard I/O package that comes with Unix. The functions in this 
package are used in the same way as the similarly named functions in Standard I/O. 

The in-line macros psio^getc and psio _putc handle characters quickly. The higher level routines 
psiojeady psio _printfy psio Jprintfy psio_write all use or act as if they use psio getc and psio _putc ; they 
can be freely intermixed. 

A file with associated buffering is called a streamy and is declared to be a pointer to a defined type PSFILE. 
psio open creates certain descriptive data for a stream and returns a pointer to designate the stream in all 
further transactions. Normally, there are three open streams with constant pointers declared in the psio.h 
include file and associated with the standard open files: 

psio_stdin standard input file 
psio_stdout 

standard output file 

psiostderr 

standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer constant EOF (-1) is returned upon end-of-file or error by most integer functions that deal with 
streams. 

Any module that uses this package must include the header file of pertinent macro definitions, as follows: 
#include "psio.h" 

The functions and constants mentioned in here are declared in that header file and need no further declara- 
tion. The constants and the following ‘functions’ are implemented as macros; redeclaration of these names 
is perilous: getCyputCy psio eofy psiojerrory psio JilenOy and psio jilearerr . 

SEE ALSO 

open(2V), close(2), read(2V), write(2V), intro(3S), fclose(3S), ferror(3S), fopen(3S), fread(3S), getc(3S), 
printf(3S), putc(3S), ungetc(3S). 

DIAGNOSTICS 

The value EOF is returned uniformly to indicate that a PSFILE pointer has not been initialized with 
psioypen, input (output) has been attempted on an output (input) stream, or a PSFILE pointer designates 
corrupt or otherwise unintelligible PSFILE data. 

LIST OF FUNCTIONS 



Name 


Description 


psio_clearerr 


stream status inquiries 


psio_close 


flush a stream 


psio_eof 


stream status inquiries 


psio_error 


stream status inquiries 


psio_fdopen 


open a stream 


psio_flush 


close or flush a stream 


psio_fileno 


stream status inquiries 
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psio_fprintf formatted output conversion 

psio_getc get character or integer from stream 

psio open open a stream 

psio_read buffered binary input/output 

psio_printf formatted output conversion 

psio j)utc put character or word on a stream 

psio_ungetc push character back into input stream 
psio write buffered binary input/output 
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Index 



Special Characters 

X, 131 



A 

acceptconnection, 131 

Action, 19, 121 

activate, 131 

addeditkeysinterest, 52 

addfunctionnamesinterest, 52 

addfunctionstringsinterest, 51 

addkbdinterests, 51 

addselectioninterests, 55 

AUEvents, 23, 120 

append, 34 

append, 34 

arccos, 131 

arcsin, 131 

arctan, 131 

array 

ExecutionStack, 125 
Interests, 125 
OperandStack, 125 
StandardErrorNames, 125 
State, 125 
arraydelete, 35 
arraydelete, 35 
arrayinsert, 35 
arrayinsert, 35 
arrayop, 35 
arrayop, 35 
autobind, 153 

currentautobind, 154 
setautobind, 154 

awaitevent, 132, 13, 21, 22, 134, 137, 144 

B 

banddevice, 151 
bindkey, 44 

bldf amily(l) — build font family description, 169, 170, 213 

blockinputqueue, 132, 26, 132, 147 

Bottom Canvas, 119 

breakpoint, 132, 133, 147 

buildimage, 132 

buttons 

AdjustButton, 83 



buttons, continued 
MenuButton, 83 
PointButton, 82 

byte stream format, 157 

c 

canvas, 14, 5 

AUEvents, 23, 120 
as canvas dictionary, 119 
as canvas object, 117 
BottomCanvas, 119 
CanvasAbove, 119 
CanvasBelow, 119 
canvastobottom, 133 
canvastotop, 133 
clipcanvaspath, 133 
Color, 120 
createdevice, 134 
createoverlay, 134 
currentcanvas, 135 
cursor, 16 

damage, see damage 
damagepath, 136 
eoreshapecanvas, 137 
eowritecanvas, 137 
eowritescreen, 137 
EventsConsumed, 15, 23, 120 
framebuffer, 43 
getcanvascursor, 138 
imagecanvas, 140 
imagemaskcanvas, 140 
insertcanvasabove, 140 
insertcanvasbelow, 141 
interest list, 23 
Interests, 121 
Mapped, 14, 120 
mapping, 14 

MatchedEvents, 23, 120 
matching events against, 23 
movecanvas, 142 
newcanvas, 142 
NoEvents, 23, 120 
opaque, 14 
Parent, 119 
readcanvas, 143 
reshapecanvas, 144 
retained, 14 
Retained, 120 
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canvas, continued 
SaveBehind, 120 
setcanvas, 144 
setcanvascursor, 145 
TopCanvas, 119 
TopChild, 119 
transparent, 14 
Transparent, 14, 120 
visibility, 14 
writecanvas, 148 
writescreen, 148 
Canvas, 19, 23, 54, 121 
event matching, 22 
in window enter and exit events, 24 
Canvas Above, 119 
CanvasBeiow, 119 
canvastobottom, 133, 14 
canvastotop, 133, 14 
case comparator, 34 
case, 34 
cdef , 98 
/changeitem 

in menu class, 77 
charpath, 151 
cid utilities, 40 
cidinterest, 40 
cidinterestlonly, 41 
classbegin, 65 
classend, 65 
classes, 63, 65 
Object, 66 
ScrollBarltem, 74 
SimpleScrollbar, 74 
clearselection, 55 
/ClientData, 37, 122 
ClientMenu, 78 
clipcanvas, 133, 136 
clipcanvaspath, 133, 133 
clock program, 109 
code, see example code 
color 

colors . ps, 32 
as color dictionary, 45 
as color object, 117 
contrastswithcurrent, 133 
currentcolor, 135 
hsbcolor, 140 
News* implementation, 7 
rgbcolor, 144 
setcolor, 145 
Color, 120 
colors.ps, 32 
compat.ps, 33 
connection management, 127 

ps_close_PostScript (), 127 
console, 43, 35 
constants, 43 

contrastswithcurrent, 16 
contacting the server, 178 
for debugging, 87 
interpreter access, 228 



contacting the server, continued 
multiple servers, 228 
NEWSSERVER, 163, 251 
remote access, 228 

setnewshost(l) — set NEWSSERVER environmi 
/ContentsAscii, 54 
/ContentsPostScript, 54 
continueprocess, 133, 147 
contrastswithcurrent, 133 
copy events, 19 
copyarea, 133, 14, 137 
copypage, 151 
countinputqueue, 134 
cps 

argument types, 99 
cdef, 98 
how to use, 97 
parameters, 99 
tagprint, 101 
tags, 101 
the .c file, 100 
the . cps file, 98 
the .h file, 100 
typedprint, 101 
cps utilities, 106 
tagprint, 147 
typedprint, 147 

versions for other languages, 163 
cps(l) \m construct C to PostScript language interface, : 
createcanvas, 35 
createcanvas, 35 
createdevice, 134, 14 
createevent, 134, 19, 132, 137, 144 
createmonitor, 134, 141, 142 
createoverlay, 134, 37 
cshow, 39 

currentautobind, 134, 144, 154 
currentcanvas, 135 
currentcolor, 135 
currentcursorlocation, 135, 16 
/currentindex 

in menu class, 76 
currentinputfocus, 59 
/currentkey 

in menu class, 76 
currentiinequality, 135, 146 
currentpath, 135, 137 
currentprintermatch, 135, 146 
currentprocess, 135 
currentrasteropcode, 135, 147 
currentscreen, 151 
currentstate, 136, 147 
currenttime, 136, 21 
currenttransfer, 151 
cursor 

building, 32 
canvas, 16 

currentcursorlocation, 16, 135 
cursor control, 52 
Cursor . ff am, 167 
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cursor, continued 

Cursorl2 . font, 167 
cursorfont, 32, 38 
font, 16, 32 
fonts, 167 
format, 168 
getcanvascursor, 138 
hotspot, 16 
images, 16 
inheriting, 16 
mask image, 16 
primary image, 16 
representation, 167 
setcanvascursor, 145 
setcursorlocation, 16, 145 
setstandardcursor, 38 
standard font, 167 
Cursor, ff am, 167 
cursor . ps, 32, 38 
Cursorl2 . font, 167 
cvas, 42 
cvas, 42 
cvis, 42 
cvis, 42 



D 

damage, 14 

clipcanvas, 133 
damagepath, 136 
eoextenddamage, 138 
extenddamage, 138 
responding to damage, 15 
typical repair sequence, 15 
/Damaged, 109 
damagepath, 136, 15, 24, 133 
dbgbreak, 90 
dbgbreakenter, 88 
dbgbreakexit, 88 
dbgprintf, 34, 90, 91 
dbgprintfenter, 89 
dbgprintfexit, 89 
de-referencing, 128 
debugging, 87 

contacting the server, 87 
dbgbreak, 88 
dbgbreakenter, 90 
dbgbreakexit, 90 
dbgcall, 92 
dgbcaiibreak, 92 
dbgcontinue, 91 
dbgcontinuebreak, 91 
dbgcopystack, 92 
dbgenter, 92 
dbgenterbreak, 88, 91 
dbgexit, 92 
dbggetbreak, 92 
dbgkill, 93 
dbgkillbreak, 93 
dbglistbreaks, 88, 90 
dbgmodifyproc, 93 
dgbpatch, 93 
dbgpatchbreak, 92 



debugging, continued 
dbgprintf, 89 
dbgprintfenter, 90 
dbgprintfexit, 91 
dbgstart, 87, 90 
dbgstop, 90 
dbgwhere, 91 
dbgwherebreak, 91 
debug.ps, 33, 87 
errored, 36 
errors, 89 

def ine_stack_token () , 105 
ps_def ine_value_token () , 105 
ps_def ine__word__token () , 106 
/delete item 

in menu class, 77 
demos 

demomenu . ps, 32 
itemdemo, 189 

newsdemos(6) — demos menu, 231 
rubber, 37 

xdemos{6) — X Window System demonstration, 253 

/destroy 

in window class, 78 
dictbegin, 36 
dictend, 36 
dictend, 36 
dictionary, 183 

colors.ps, 32 
creating your own, 184 
de-referencing, 128 
dictbegin, 36 
magic dictionaries, 117 
new News types, 117 
size of userdict, 152 
system, 32, 183 
systoklst.ps, 32 
UnloggedEvents, 45 
user, 183 

DictionaryStack, 124 

distribution mechanism, see event distribution 
doit, 66 

dumpf ont(l) — dump font in another format, 169, 170, 217 
dumpsys, 136 

E 

echo, 151 
emptypath, 136 
enumeratefontdicts, 136 
environment variables 
getenv, 138 
putenv, 143 
eoclipcanvas, 136 
eocopyarea, 137 
eocurrentpath, 137 
eoextenddamage, 138 
eoreshapecanvas, 137 
eowritecanvas, 137, 148 
eowritescreen, 137, 137, 148 
error 

accept, 124 
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error, continued 
dictfull, 124 
dictstackoverflow, 124 
dictstackunderflow, 124 
execstackoverflow, 124 
interrupt, 124 
invalidaccess, 124 
invalidexit, 124 
invalidfileaccess, 124 
invalidfont, 124 
invalidrestore, 124 
ioerr, 124 
killprocess, 124 
limitcheck, 124 
nocurrentpoint, 124 
none, 124 
rangecheck, 124 
stackoverflow, 124 
stackunderflow, 124 
syntaxerror, 124 
typecheck, 124 
undefined, 124 
undefinedfilename, 124 
undefinedresult, 124 
unimplemented, 124 
unmatchedmark, 124 
unregistered, 124 
VMerror, 124 
error handling, 127 
ErrorCode, 124 
ErrorDetailLevel, 125 
errored, 36 
errors, 36 
event, 6 

absorption, 23 
as event dictionary, 121 
as event object, 117 
awaitevent, 132 
blockinputqueue, 132 
boundary crossing events, 24 
client-generated events, 19 
consumption, 15 
copy and events, 19 
createevent, 134 
distribution, 21 
eventmgr interest, 38 
exclusivity, 23 
expressinterest, 20, 137 
geteventlogger, 139 
ideal, 20 
interest lists, 23 
interest matching, 21 
interests, 20 

interests and forkeventmgr, 37 
Interests key in process, 125 
keystrokes, 24 
matching, 21 

order of interest matching, 23 
queue, 21 
recallevent, 143 
receiving events, 21 
redistributeevent, 143 
revokeinterest, 20, 144 



event, continued 
sendevent, 144 
seteventlogger, 145 
synchronization, 25 
synthetic events, 19 
types of events, 24 
event fields 

Action, 19, 21, 121 
Canvas, 19, 22,24, 121 
ClientData, 122 
EventsConsumed, 15, 23 
Exclusivity, 20, 122 
Interest, 122 
Isinterest, 19, 20, 122 
IsQueued, 20, 122 
KeyState, 122 
Name, 19,21, 122 
Priority, 20, 23, 123 
Process, 22, 123 
Serial, 20, 123 

Timestamp, 19, 24, 123, 141 
XLocation, 19, 123 
YLocation, 19, 123 
event logging 

eventlog.ps, 33 
eventlog, 45 
eventmgrinterest, 38 
events 

/Damaged, 24 
/EnterEvent, 24 
/ExitEvent, 24 
//LeftMouseButton, 24 
/MiddleMouseButton, 24 
/Mouse Dragged, 24 
/RightMouseButton, 24 
/DownTransition, 24 
logging, 26, 45 
mouse, 24 
timer, 24 
unlogging, 45 
/UpTransition, 24 
window crossings, 24 
EventsConsumed, 15, 23, 120 
example code 

interactive News server session using psh, 178 
lines, 80 
periodic events, 27 
roundclock, 109 
setting cursor shape, 38 
using the window and menu packages, 80 
example programs 

rubber-banding, 37 
test, psh, 180 
Exclusivity, 20, 23, 122 
Execee, 125 
executeonly, 151 
ExecutionStack, 125 
executive, 87, 178 

expressinterest, 137, 20, 21, 132, 134, 143, 144 
extenddamage, 138 
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F 

file 

raster, 143 
file, 138 
fillcanvas, 39 
findfilefont, 42 
findfiiefont, 42 
fmdfont 

Building News fonts, 170 
/flipiconic 

in window class, 79 
font, 167 

vfont format, 170 
Ascn version, 168 
binary version, 169 

bldfamily(l) — build font family description, 169, 213 

building ordinary fonts, 170 

Cursor, ffam, 167 

Cursorl2 , font, 167 

dictionary generation, 169 

directory, 169 

dumpf ont(l) — dump font in another format, 169, 217 
family, 170 
generation, 167 
iconedit, 168 
iconfont, 32 
mkiconfont, 168 
representation, 167 
font object, 42 
font utilities, 41 
cvas, 42 
cvis, 42 
findfilefont, 42 
fontascent, 41 
fontdescent, 42 
fontheight, 41 
stringbox, 42 
fontascent, 41 
fontascent, 41 
fontdescent, 42 
fontdescent, 42 
fontheight, 41 
fontheight, 41 
fork, 147 
forkeventmgr, 37 
forkitems, 190 
ForkPaintClient?, 79 
forkunix, 138, 32 
format 

byte stream, 157 
fprintf, 35 
fprintf, 35, 43 
framebuffer, 43 
framedevice, 151 
FrameLabel, 78, 79 
function keys 
assigning, 43 
repeating, 44 



G 

garbage collection, 128 
de-referencing, 128 
get, 184 

getanimated, 36 
getcanvascursor, 138, 16, 145 
getcanvaslocation, 138, 142 
getclick, 37 
getenv, 138 

geteventlogger, 139, 145 
getkeyboardtranslation, 139 
getkeyboardtranslation, 139, 141 
getmousetranslation, 139 
getrect, 37 
getselection, 56 
getsocketlocaladdress, 139 
getsocketpeername, 139 
getvalue, 34 
getvalue, 34 
getwholerect, 37 
global interest list, 21, 23 
globaiinterest, 140, 21 
graphics utilities, 39 
graphicsstate 

as graphicsstate dictionary, 123 
as graphicsstate object, 117 
currentstate, 136 
setstate, 147 

H 

hasfocus, 60 
hsbcolor, 140 

I 

icon 

fonts, 167 
icon . ps, 32 
iconfont, 32 
iconedit, 168 

Iconlmage, 78 
IconLabel, 78 
image 

buildimage, 132 
imagecanvas, 140 
imagemaskcanvas, 140 
imagecanvas, 140, 15 
imagemaskcanvas, 140 
implementation limits, 152 
init . ps 

size of userdict, 152 
init . ps, 31, 82, 174, 183 
initclip, 144 
PaintRoot, 32 
input, 19 

addeditkeysinterest, 52 
addfunctionnamesinterest, 52 
addfunctionstringsinterest, 51 
addkbdinterests, 51 
extended input system, 49 
lasteventtime, 141 
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input, continued 

revokekdbinterests, 5 1 
input events, 19, see also Event Fields 
input focus, 59 

currentinputfocus, 59 
hasfocus, 60 
setfocusmode, 60 
setinputfocus, 59 
insertcanvasabove, 140, 14 
insertcanvasbelow, 141, 14 
/insertitem 

in menu class, 76 
insetrect, 39 
insetrrect, 40 
interactive 

example, 178 
server, 178 
interest matching 
order of, 23 
Interest, 122 
interests, see events 

giobalinterestlist, 140 
Interests, 125 
Interests, 121 
interpreter access, 228 
introduction 

NeWS I/O library functions, 255 
invertmatrix, 151 
Isinterest, 20, 122 
IsQueued, 122 
item, 189 

forkitems, 190 
liteitem.ps, 33 
pain ti terns, 190 
itemdemo, 189 

J 

journalend, 42 
journalling, 42 
begin, 42 
controls, 43 
endjoumai, 42 
internal variables, 43 
journal, 42 
journal.ps, 33 
record, 42 
replay, 42 
stop, 42 

journalUng{l) — record and playback package, 219 
journalplay, 42 
journalrecord, 42 

K 

kbd_mode(l) — change keyboard translation mode, 221 
News and Sunview, 176 
key mapping, 43 
keyboard 

function key assignment, 52 
keyboard editing, 52 
repeating keys, 44 
keyboard input 



keyboard input, continued 
Asai, 50 

function keys, 51, 52 
reset, 221 

keyboardtype, 141, 139, 145 
keys 

bindkey, 44 
mapping, 43 
repeat . ps, 33 
repeating, 44 
unbindkey, 44 
Key State, 122 
kiilprocess, 141, 131 
killprocessgroup, 141, 131 

L 

lasteventtime, 141, 21 
library functions 

introduction to NeWS standard I/O, 255 
lightweight processes, see processes 
line quality 

currentlinequality, 135 
setiinequality, 146 
lines example code, 80 
Liteltem, see item 
liteitem.ps, 33, 189 
LiteMenu, see menu 
litemenu . ps, 32, 73 
litetext . ps, 33 
liteUI user interface package, 50 
liteUI . ps, 32, 49, 122 
litewin . ps, 32, 36 
Lite Window, see window 
litewindow . ps, 73 
localhostname, 141 
logging, 45 
logging events, 26 

M 

magic numbers, 159 
/map 

in window class, 78 
Mapped, 120 
MatchedEvents, 23, 120 
max, 141 
menu 

/changeitem, 77 
/currentindex, 76 
/currentkey, 76 
/deleteitem, 77 

example program test, psh, 180 
/insertitem, 76 
keys, 75 

litemenu . ps, 32 
modifying the root menu, 184 
/new, 75 
/popup, 76 
root menu, 223 
/searchaction, 76 
/searchkey, 76 
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menu, continued 
/showat, 76 
menu keys, 75 
menu methods, 74 
min, 141 

missing PostScript language operators, 151 
mkiconfont, 168 
modifying the server, 183 
changing defaults, 185 
changing menus, 184 
changing the window user interface, 83 
saving keystrokes, 93, 184 
startup.ps, 32 
user . ps, 32, 183 
modifyproc, 35 
modifyproc, 35 
monitor 

as monitor object, 118 
createmonitor, 134 
monitor, 141, 134, 142 
monitorlocked, 142, 134, 141 
mouse, see cursor 
/move 

in window class, 79 
movecanvas, 142, 14, 138 
multiple servers, 228 

N 

Name, 19, 122 
new, 66, 73, 191 

in Liteltemclass, 191 
in menu class, 75 
in window class, 77 
new#, 184 
newcanvas, 142, 14 
newprocessgroup, 142, 141 

News buffered I/O library functions, introduction to, 255 
NeWS I/O library functions, introduction to, 255 
News protocol, 157 
NeWS type extensions 
canvas, 117 
color, 117 
event, 117 
graphicsstate, 117 
monitor, 118 
process, 118 
shape, 118 

news_server(l) — NeWS server program, 31, 174, 223 
debugging server, 174 
three binaries, 174 

newsdemos(6) — NeWS demonstrations, 23 1 

newshost(l) — NeWS network security control., 237 

NEWSSERVER, 163, 179 

noaccess, 151 

NoEvents, 23, 120 

nuildevice, 151 

nuUdict, 43 

nullproc, 43 

nuilstring, 43 



o 

object tables, 158 
Object, 66 
objects 

cleanup, 126 

connection management, 127 
error handling, 127 
management, 127 
process management, 127 
server function, 126 
offscreen images, 15 

omitted PostScript language operators, 151 
on(l), 179 

online reference using NeWS — man, 243 

opaque canvases, 14 

OperandStack, 125 

operators, 205 

ovalframe, 40 

ovalpath, 40 

overlay canvas 

createoverlay, 134 
getanimated, 37 
overview ( 1 ) , 174, 175, 223 

p 

PostScript language files loaded by the server, see ps files 
packages, 73, 63 

interface description format, 74 
/paint, 190 

in window class, 79 
/paintclient 

in window class, 79 
PaintCIient, 78, 178 
/paintframe 

in window class, 79 
/painticon 

in window class, 79 
paintitems, 190 
Parent, 119 
pathforallvec, 142 
pause, 143, 13, 81 
pointinpath, 143 
points2rect, 39 
/popup 

in menu class, 76 
portability 

retained, 142 

PostScript language extensions 
in * . ps files, 33 
pprintf 0 , 163 

previewing PostScript language graphics, 178 
printer compatability, 32 
printemame, 32 
printf, 34 

printf, 34, 67, 89, 194 
Priority, 20, 23, 123 
process 

as object, 118 
as process dictionary, 124 
scheduling policy, 13 
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process keys 

Dictionary Stack, 124 
Error Code, 124 
Execee, 125 
Executions tack, 125 
Interests, 125 
OperandStack, 125 
State, 125 

process management, 127 
garbage collection, 128 
killing an application, 127 
Process, 123 

event matching, 22 
processes, 13 
activate, 131 
breakpoint, 132 
continueprocess, 133 
currentprocess, 135 
forking, 74 
forkunix, 138 
killprocess, 141 
killprocessgroup, 141 
newprocessgroup, 142 
pause, 143 
suspendprocess, 147 
waitprocess, 147 
prompt, 151 
* .ps files, 31 

colors.ps, 32 
compat.ps, 33 
cursor . ps, 32, 38, 167 
debug.ps, 33, 87 
demomenu . ps, 32 
eventlog . ps, 33 
file location, 3 1 
icon.ps, 32 

init . ps, 31, 82, 152, 168, 174, 183 
journal .ps, 33 
liteitem.ps, 33, 189 
litemenu . ps, 32, 73 
litetext . ps, 33 
liteUI . ps, 32, 49, 122 
litewin.ps, 32, 36 
litewindow . ps, 73 
menu . ps, 168 
organization, 31 

PostScript language procedures they define, 33 

repeat.ps, 33 

startup.ps, 32, 151, 183 

statusdict.ps, 32 

systoklst . ps, 32 

user .ps, 32, 83, 87, 93, 151, 183 

util .ps, 32 

ps_define_stack_token () , 105 
ps_def ine_value_token ( ) , 105 
ps_define_word_token () , 106 
pscanf 0 , 164 

psh(l) — News PostScript shell, 177, 81, 87, 178, 239 
example program test, psh, 180 
psio(3) — News buffered input/output package, 255 
psload{\) — display load average under NeWS, 241 
man — online display of reference pages using NeWS, 243 



psterm(l) — NeWS terminal emulator, 180, 225, ^ 
psview(l) — PostScript language previewer, 178h^.^/ 
put, 184 

putenv, 143 

R 

random, 143 
Rank, 54 
raster files, 143 
rasteropcode 

c ur re ntraster opcode, 135 
setrasteropcode, 146 
readcanvas, 143 
recallevent, 143, 20, 144 
rect, 38 
rect2points, 39 
rectangle utilities, 38 
rectframe, 40 
rectpath, 39 
rectsoverlap, 39 

redistributeevent, 143, 20, 21, 25, 26, 132, 134, 137, 144 

remote access, 228 

renderbands, 151 

resetfile, 151 

/reshape 

in window class, 78 
reshapecanvas, 144, 14, 137, 142 
/reshapefromuser 

in window class, 78 
restore, 151 
retained 

portability, 142 
retained canvases, 14 
Retained, 120 
reversepath, 151 
revokeinterest, 144, 20, 137 
re vokekbdinte rests, 51 
rgbcolor, 144 

roundel ock example code, 109 

rrectframe, 40 
rreetpath, 40 
rshow, 39 
rubber, 37 

s 

save, 151 
SaveBehind, 120 

say(l) — execute PostScript language, 177, 249 

scalefont 

building News fonts, 170 
scene, 5 
scrollbars, 74 
/searchaction 

in menu class, 76 
/searchkey 

in menu class, 76 
security 

implementation, 128 
selection events, 56 
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selection events, continued 
Deselect, 58 
ExtendSelectionTo, 57 
SelectionRequest, 58 
/SetSelectionAt, 56 
ShelveSelection, 58 
selection library procedures, 54 
/SelectionHoIder, 54 
/SelectionLastIndex, 54 
/SelectionObjsize, 54 
selectionrequest, 55 
SelectionRequester, 54 
/SelectionResponder, 54 
selectionresponse, 55 
selections, 53 

addselectioninterests, 55 
clearselection, 55 
getselection, 56 
selectionrequest, 55 
selectionresponse, 55 
setselection, 55 
/SelectionStartlndex, 54 
self, 64 
seif, 66 
send, 65, 64 
sendcidevent, 41 

sendevent, 144, 20, 21, 132, 134, 137, 143 
Serial, 123 
server function, 126 
setautobind, 144, 134, 154 
setcanvas, 144 

setcanvascursor, 145, 16, 38, 138 
setcolor, 145 

setcursorlocation, 145, 16 
seteventlogger, 145 
setfileinputtoken, 145 
setbleinputtoken, 145 
setfocusmode, 60 
sethsbcolor, 16, 145 
setinputfocus, 59 
setkeyboardtranslation, 145 
setkeyboardtranslation, 145, 139, 141 
setlinequality, 146, 135 
setmousetransiation, 146 

setnewshost(l) — set NEWSSERVER environment, 163, 179, 
251 

setpath, 146 

setprintermatch, 146, 135 
setrasteropcode, 146, 135 
setrgbcolor, 16, 145 
setsccbatch, 32 
setscreen, 151 
setselection, 55 
setstandardcursor, 38 
setstate, 147, 136 
settransfer, 151 
setvalue, 34 
setvalue, 34 
shape 



shape, continued 

as shape dictionary, 126 
as shape object, 118 
/showat 

in menu class, 76 
showpage, 151 
sleep, 36 
sleep, 36 
sockets 

acceptconnection, 131 
getsocketlocaladdress, 139 
getsocketpeername, 139 
priority of connection, 228 
sprintf, 34 
sprintf, 34 

StandardErrorNames, 125 

start, 151 

starting News, 174 

startkeyboardandmouse, 147 

startup.ps, 32, 183 

State, 125 

statusdictps, 32 

store, 184 

stringbbox, 42 

stringbox, 42 

stroke 

currentlinequality, 135 
setlinequality, 146 
strokecanvas, 39 
SunView 

keyboard state if NeWS crashes, 221 
SunView 1 

and News on the Sun-3/ 1 10, 176 
coexistence with News, 174 
super, 64 
super, 66 

suspendprocess, 147, 13, 133 
systoklst . ps, 32 

T 

tagprint, 103 
tagprint, 147 
tags, 101 
text 

display using say(l), 177 
text utilities, 41 
time values, 19 

event queue, 21 
resolution, 123 

Timestamp, 19, 21, 24, 123, 141 
/tobottom 

in class window, 80 
tokenization, 105 
tokens, 105 
TopCanvas, 119 
TopChild, 119 
/totop 

in window class, 80 
translate, 151 
transparent canvases, 14 
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Transparent, 120 
type extensions, 117 
typedprint, 103 
typedprint, 147 

u 

unbindkey, 44 

unblockinputqueue, 147, 26, 132 
undef, 147 
uniquecid, 40 
UnknownRequest, 55 
unlogging, 45 
/unmap 

in window class, 79 
unregistered 

error accessing process keys, 124 
user interface 
default, 82 

window management, 227 
user .ps, 32, 83, 87, 93, 183 
usertime, 151 
usertoken, 105 
utilities 

cps, 106 
font, 41 
misc., 33 
text, 41 
util . ps, 32 

V 

verbose?, 32 

w 

waitprocess, 147, 37, 131 
window 

/destroy, 78 

example program test, psh, 180 

/flipiconic, 79 

ForkPaintClient?, 79 

litewin . ps, 32 

/map, 78 

/move, 79 

/new, 11 

/paint, 79 

/paintclient, 79 

/paintframe, 79 

/paint icon, 79 

/reshape, 78 

/reshapefromuser, 78 

scrollbars, 74 

/tobottom, 80 

/totop, 80 

/unmap, 79 

window management, 227 
window methods, 77 
writecanvas, 148, 137 
writescreen, 148, 137, 148 



X 

xdemos{6) — X Window System demonstration, 253 
XLocation, 19, 123 

Y 

YLocation, 19, 123 
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